feat: add GitHub API caching

[flemzord]

Summary

• add cache module with manager, memory storage, and tests
• wire caching into GitHubClient plus CLI and config schema
• extend validator warnings and GitHub client tests for cache behaviour

Closes #11

Testing

• npm run lint
• npm test
• npm run test:coverage

---

Summary by cubic

Adds a configurable GitHub API caching layer to cut rate-limit usage and speed up repeated requests. Caching is optional, uses in-memory storage by default, and is wired into the CLI, config, and GitHubClient with safe invalidation on writes.

• New Features

  • New cache module with CacheManager, in-memory storage, TTL per namespace, size cap eviction, stats, and namespace invalidation.
  • GitHubClient now caches: current user, repo list, repo details, branches, branch protection, collaborators, team permissions, security settings, and vulnerability alerts. Write operations invalidate relevant caches.
  • Accepts either a CacheManager instance or cache config in GitHubClient options.
  • Config adds a cache section (enabled, storage, storagePath, maxSize, ttl, adaptive/predictive/etag/compression). Validator warns for unsupported redis and missing filesystem path; unsupported storage falls back to memory.
  • CLI reads cache config and constructs CacheManager. Added unit and integration tests.

• Migration

  • Caching is disabled by default. Enable via config:
    cache:
    enabled: true
    ttl:
    default: 900
  • Filesystem and redis storage are not yet supported; memory is used with a warning. No breaking changes.

[flemzord]

Link to #11

[cubic-dev-ai]

7 issues found across 15 files

Prompt for AI agents (all 7 issues)

Understand the root cause of the following 7 issues and fix them.


<file name="src/config/schema.ts">

<violation number="1" location="src/config/schema.ts:115">
Schema allows unsupported cache storage values (&#39;filesystem&#39;, &#39;redis&#39;), which will silently fall back to memory at runtime. Consider restricting to supported options or adding validation/warnings for all unsupported values.</violation>
</file>

<file name="src/github/client.ts">

<violation number="1" location="src/github/client.ts:105">
Current user cache key should not depend on org; use a stable owner like SELF_CACHE_OWNER to avoid duplicate entries.</violation>

<violation number="2" location="src/github/client.ts:530">
Use error.status to detect 403 instead of parsing the error message string when deciding whether to log.</violation>

<violation number="3" location="src/github/client.ts:561">
Brittle 403 detection via error.message.includes(&#39;403&#39;); check error.status instead to reliably handle permission-denied responses.</violation>
</file>

<file name="src/cache/memory-storage.ts">

<violation number="1" location="src/cache/memory-storage.ts:8">
Returning 0 on serialization failure defeats size-based eviction; non-serializable entries won’t count toward the budget, risking unbounded memory growth.</violation>
</file>

<file name="src/cache/cache-manager.ts">

<violation number="1" location="src/cache/cache-manager.ts:23">
stableStringify collapses Date/Map/Set/RegExp (and similar) to &#39;{}&#39; causing cache key collisions; handle these types explicitly or use a JSON replacer.</violation>

<violation number="2" location="src/cache/cache-manager.ts:177">
TTL override is not validated; NaN/Infinity produce non-expiring entries. Guard override with Number.isFinite before using it.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[github-actions]

📊 Build Report

Bundle Size: 1.15 KB
Node Versions Tested: 18, 20, 22
All Checks: ✅ Passed

Details

• Linting (BiomeJS, Knip, TypeScript): ✅
• Tests with coverage: ✅
• Build: ✅
• Integration test: ✅

Generated for commit 8999731

[flemzord]

Added the link to #11 in the PR description.

[flemzord]

@cubic-dev-ai addressed the cache review feedback:\n- tighten cache storage support to only and reject unsupported values during validation.\n- hardened cache key generation and TTL handling (stable serialization, invalid TTL guard).\n- ensured size-based eviction counts non-serializable entries.\n- current user cache now uses a stable namespace and GitHub 403 responses rely on codes.

[flemzord]

@cubic-dev-ai addressed the cache review feedback:

• cache schema/validation now only accept the supported memory storage mode.
• cache key serialization handles Maps/Sets and rejects invalid TTL overrides.
• size accounting counts non-serializable values so eviction still works.
• current user caching uses a single namespace and 403 handling now relies on error.status.