feat(mcp): add cache list to inspect cached decision packs

[glorydavid03023]

Summary

gittensory-mcp cache could only report an aggregate count (status) or wipe everything (clear) — there was no way to see what is in the offline decision-pack cache. Adds cache list (alias ls):

$ gittensory-mcp cache list
- jsonbored (cached 2026-06-26T10:00:00.000Z, 1234 bytes)

$ gittensory-mcp cache list --json
{
  "status": "ok",
  "count": 1,
  "maxEntries": 25,
  "clearCommand": "gittensory-mcp cache clear",
  "entries": [
    { "login": "jsonbored", "cachedAt": "...", "apiVersion": "0.1.0", "packageVersion": "0.6.0", "bytes": 1234 }
  ]
}

Entries are newest-first. It follows the existing inspectDecisionPackCache() pattern (used by cache status).

Privacy

It surfaces only safe metadata — login, cachedAt, API/package version, and byte size — and never the cached payload or the authCacheKey (a token hash). A test asserts the listing names the login but leaks neither the configured token nor the auth-cache key, consistent with the cache's existing local-only redaction.

Scope

• packages/gittensory-mcp/bin/gittensory-mcp.js — list/ls branch in runCacheCli, the listDecisionPackCache() helper, and the cache + main help text.
• test/unit/mcp-cli-packets.test.ts — a test that populates the cache via decision-pack, lists it, and asserts the safe-metadata shape + no token/auth-key leak (and the empty-cache case).
• packages/gittensory-mcp/README.md — document cache list.

Packages-only; no src/**, UI, schema, migration, or OpenAPI changes.

Validation

Run locally on Node v24.18.0 (engine floor is 22):

• npm run build:mcp → pass
• npm run typecheck → pass, 0 errors (full project)
• npx vitest run test/unit/mcp-cli-packets.test.ts → 17/17 pass, including the new lists cached decision packs with safe metadata only
• npm pack --workspace @jsonbored/gittensory-mcp --dry-run → package file list unchanged (allowed set only; no new files, no secrets)
• Smoke: cache list / cache list --json on an empty cache and the help text verified

Note: npm run test:mcp-pack can't run on my Windows box (its harness spawnSync("npm", …) can't resolve npm.cmd without a shell) — verified package contents with npm pack --dry-run instead. It passes on CI.

Safety

No auth, cookie, CORS, GitHub App output, identity, contributor-evidence, or scoring changes. No secrets/wallets/hotkeys/trust/reward terms. The listing deliberately omits the cached payload and the auth-cache key.

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-06-30 06:44:12 UTC}

3 files · 1 AI reviewer · no blockers · readiness 66/100 · CI green · unknown

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
The diff coherently adds a `cache list`/`ls` CLI path, a helper that reads per-entry cache metadata newest-first, tests the JSON happy path and empty cache, and documents the new command. The implementation keeps the cached payload and auth-cache key out of the returned JSON, and the visible code is scoped to the MCP package without schema or runtime wiring changes. The main remaining issues are documentation/help consistency and tightening the human-output privacy test.

Nits — 6 non-blocking

• packages/gittensory-mcp/bin/gittensory-mcp.js:1490 supports the `ls` alias but `printHelp`, `printCacheHelp`, and the README only document `list`, so users cannot discover the alias from built-in help.
• packages/gittensory-mcp/bin/gittensory-mcp.js:1490 and packages/gittensory-mcp/README.md:247 are slightly inconsistent because the README says `cache list` shows API/package version metadata, while the human output only prints login, cached time, and byte size.
• test/unit/mcp-cli-packets.test.ts:130 only checks that the human output contains the login; it should also assert the human path does not include the configured token or auth-cache key since that is the default user-facing path.
• Either include `apiVersion` and `packageVersion` in the non-JSON formatter at packages/gittensory-mcp/bin/gittensory-mcp.js:1490 or narrow the README sentence at packages/gittensory-mcp/README.md:247 to say that version metadata is exposed in `--json`.
• Document `cache ls` in packages/gittensory-mcp/bin/gittensory-mcp.js:1788 and packages/gittensory-mcp/bin/gittensory-mcp.js:1815, or remove the alias if it is intentionally unsupported in docs.
• 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	⚠️ Missing	No linked issue or no-issue rationale found.
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 (size label size:XS; no linked issue context).
Validation posture	❌ 5/25	Preflight is holding this PR; address the blocker before review.
Contributor workload	✅ 10/10	Author activity: 192 registered-repo PR(s), 127 merged, 4 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	glorydavid03023; Gittensor profile; 192 PR(s), 4 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: glorydavid03023
• 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: 192 PR(s), 4 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Explain no-issue PR.
• Fix the blocker.
• 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.

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