feat(dx): codelens sessions command — view install session log, rotation, --json/--raw (closes #64 phase-2)

[Wolfvin]

Summary

Implements Phase 2 of issue #64 — codelens sessions command for viewing install session logs.

(Supersedes the closed PR — that PR was based on the Phase 1 branch feat/issue-64-doctor-phase-1, which got deleted when PR #132 was merged. This PR is rebased directly onto main and contains only the Phase 2 commit.)

sessions reads the install-session log that setup.sh appends to on every run, and displays the last N sessions in a human-readable format (or JSON for programmatic access). This is the "what happened last time I ran setup?" debugging tool.

Depends on #132 (Phase 1, MERGED) — Phase 2's dispatcher changes build on Phase 1's _doctor_printed_text pattern (now generalized to also cover _sessions_printed_text).

Files

New:

• scripts/commands/sessions.py — full sessions command: read JSON sidecar (fallback to MD parsing), --entries N, --raw, --json, --config-dir, automatic rotation when log exceeds 1 MB (keep last 50)
• tests/test_sessions.py — 24 tests covering JSON sidecar reading, MD fallback, --entries filtering, --json/--raw output modes, rotation (over-threshold + idempotent), setup.sh integration (real subprocess), CLI smoke

Modified:

• setup.sh — appends a Markdown + JSON session entry on every run. Captures: timestamp, duration, Python/OS/arch, agents detected (Claude Code, Cursor, Continue), deps installed, warnings, errors, exit code. Uses CODELENS_CONFIG_DIR env var for test isolation.
• scripts/codelens.py — dispatcher generalized to handle both _doctor_printed_text and _sessions_printed_text signals (so sessions doesn't double-print)
• README.md, SKILL.md, SKILL-QUICK.md, pyproject.toml, skill.json, scripts/graph_model.py — auto-synced by python3 scripts/sync_command_count.py --apply to reflect 68 → 69

Session log format

~/.codelens/session.md (Markdown, human-readable):

# CodeLens install sessions

## 2026-06-28T09:14:31Z — setup

- **duration_sec**: 16
- **exit_code**: 0
- **python**: 3.12.13
- **os**: Linux
- **arch**: x86_64
- **agents_detected**: claude-code
- **deps_installed**: tree-sitter tree-sitter-html tree-sitter-css ...
- **warnings**: watchdog install failed

~/.codelens/session.json (JSON sidecar, programmatic access):

[
  {
    "timestamp": "2026-06-28T09:14:31Z",
    "duration_sec": 16,
    "exit_code": 0,
    "python": "3.12.13",
    "os": "Linux",
    "arch": "x86_64",
    "agents_detected": ["claude-code"],
    "deps_installed": ["tree-sitter", "tree-sitter-html", ...],
    "warnings": "watchdog install failed",
    "errors": null,
    "title": "setup"
  }
]

Key design decisions

1. JSON sidecar is the source of truth; Markdown is for humans. When the sidecar is missing or corrupt, sessions falls back to parsing the Markdown log. A corrupted sidecar must NOT crash the command.
2. Rotation is automatic and idempotent. When the JSON sidecar exceeds 1 MB, trim to most recent 50. Runs on every sessions invocation — no cron job needed.
3. --entries 0 means "all". Default is 5 (matches the issue spec). Most-recent-first display order.
4. --json prints just the sessions array (not the full result dict) so jq can pipe cleanly.
5. --config-dir for test isolation. Tests use tmp_path + --config-dir so they never touch the user's real ~/.codelens/.
6. setup.sh writes both formats. Markdown for --raw reading, JSON for --json programmatic access.
7. CODELENS_CONFIG_DIR env var. Lets tests override the default ~/.codelens/ location.
8. Read-only command. sessions never writes sessions — only setup.sh writes them.

Acceptance criteria

• codelens sessions shows last 5 install sessions by default
• --entries N controls how many sessions to show (0 = all)
• --json produces valid JSON array for programmatic access
• --raw prints the Markdown log verbatim
• --config-dir overrides default ~/.codelens/
• Rotation: when log exceeds 1 MB, trim to last 50 (idempotent)
• setup.sh appends a session entry on every run (both MD and JSON)
• sync_command_count.py --apply run — all docs reflect 69 commands
• Corrupted JSON sidecar does NOT crash the command (falls back to MD)

(Phases 3–4 of #64 — install.sh --dry-run/--self-test/--uninstall, codelens upgrade — are out of scope for this Phase 2 PR.)

Test results

• 24 new tests in tests/test_sessions.py — all pass
• Phase 1 tests (tests/test_doctor.py, 32 tests) — still pass (no regression)
• setup.sh integration tests verify the script actually writes session entries (subprocess test, not mocked)

Closes #64 (phase-2).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
12 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud