perf: OAuth token cache, lazy command loading, parallel bulk load (#247)

[cdot65]

Summary

Three measured performance improvements: per-context OAuth token cache (no auth roundtrips on consecutive commands), lazy command loading (startup -74%), and concurrent bulk loads.

Metrics (same method as baseline: /usr/bin/time -p, 5 runs, .venv/bin/scm)

Metric	Before	After
scm --version wall	0.42–0.45s	0.11s
scm --help wall	0.38s	0.11s
import scm_cli.main	302ms	85ms
OAuth token + JWKS fetch	every invocation	cached until expiry (~15min tokens)
bulk load N objects	2N serial calls	5-way concurrent (order-sensitive types stay serial)

Changes

• utils/token_cache.py: per-context cache in ~/.scm-cli/cache/ (0600), 5-min expiry buffer, corrupt-tolerant, SCM_NO_TOKEN_CACHE=1 kill-switch; SCMClient reuses valid tokens via bearer-mode session, auto-supplies commit admin, clears cache when the API rejects a token
• main.py: lazy TyperGroup — help listings render from static metadata, modules import only on dispatch; importlib.metadata deferred into --version
• utils/bulk.py + all 72 non-order-sensitive load commands migrated to run_bulk (5 workers, SCM_BULK_WORKERS); security/NAT/PBF/QoS rule loads and folder hierarchy load stay sequential to preserve ordering
• Docs: token cache + bulk concurrency sections in configuration guide

Testing

• 1316 passed, 29 skipped (55 new: cache unit+integration, lazy-import subprocess tests, bulk runner, per-module concurrency tests)
• lint/ruff/mypy clean; docs build passes

Notes

• Parallel abort-on-first-error loads may have in-flight items complete before aborting (was: strictly stopped at first failure) — flagged intentionally, success messages suppressed
• scm <group> --help for a specific category still imports that category's module (dispatch), which is the desired boundary

Checklist

• Tests written first (TDD)
• All tests passing
• Lint/format/typecheck clean
• Documentation updated
• Changeset added

Closes #247

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[github-actions]

Failed to generate code suggestions for PR