hanzoai/dev
2
0
Fork 0
mirror of https://github.com/hanzoai/dev.git synced 2026-10-17 15:34:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0089b863d87f328a67cc94b1e661d3fe26e6a9ea
dev/UPSTREAM_PARITY_CHECKLIST.md
T
James PeterandHanzo Dev 7deab83fc3 chore: complete legacy test retirement and upstream crate adoption 
This commit completes Phase 1 of the codebase cleanup plan documented in
ROADMAP.md and related migration documents.

Major changes:
- Removed legacy test suites from code-rs/ crates (~35,000 lines)
- Adopted upstream codex-mcp-client and codex-responses-api-proxy
- Deleted TUI compat layer, agent task planning docs, and orphaned modules
- Updated documentation to reflect current state and future phases

Test Coverage:
- Deleted tests from: app-server, apply-patch, chatgpt, cli, core, exec,
  login, mcp-server
- Documented 9 remaining coverage gaps requiring new tests (see
  docs/migration/legacy-tests-retirement.md)
- Preserved smoke test infrastructure in tui/tests/ui_smoke.rs

Crate Adoptions:
- mcp-client: Now re-exports codex-mcp-client with fork-specific buffer config
- responses-api-proxy: Now re-exports codex-responses-api-proxy with minimal
  wrapper
- mcp-types: Updated to use upstream types where possible

TUI Cleanup:
- Removed compat.rs ratatui adapter layer
- Deleted obsolete modules: app_backtrack, custom_terminal, scroll_view,
  text_block, transcript_app
- Archived agent_tasks/ planning docs to docs/archive/

Documentation Updates:
- ROADMAP.md: Marked Phases 1-2 complete, updated next actions
- TEST_SUITE_RESET.md: Documented Phase 1 completion
- DEAD_CODE_INVENTORY.md: Updated with deletion outcomes
- Added docs/migration/legacy-tests-retirement.md with 6-week plan
- Added docs/maintenance/prompt-architecture.md

Next Steps (Phase 2-3):
- Port critical test coverage (9 test files identified)
- Expand smoke test scenarios
- Continue upstream tracking per monthly cadence

See docs/migration/ for detailed migration status and roadmap.

Co-authored-by: Hanzo Dev <[email protected]>
2025-10-06 05:15:48 +10:00

7.4 KiB
Raw Blame History

Upstream Parity Maintenance Checklist

Quick reference for maintaining parity with codex-rs MCP components.

Status (2025-10-06): MCP crates re-export upstream codex-rs crates. Monitoring now focuses on upstream commits and wrapper glue.

Monthly Cadence

We follow a two-step cycle aligned with the broader upstream diff process (see docs/maintenance/upstream-diff.md).

First Monday — Quick Diff

  • Fetch latest upstream: git fetch upstream
  • Inspect new commits: git log HEAD..upstream/main --oneline
  • Run structural diff: ./scripts/upstream-merge/diff-crates.sh --all
  • Review summary: cat .github/auto/upstream-diffs/SUMMARY.md
  • Check key crates for breaking changes:
    • mcp-client/
    • responses-api-proxy/
    • process-hardening/
    • mcp-types/
  • Decide whether a merge plan is required this month

Second Monday — Merge Planning (if needed)

  • Highlight critical changes: ./scripts/upstream-merge/highlight-critical-changes.sh --all
  • Review critical summary: cat .github/auto/upstream-diffs/critical-changes/CRITICAL-SUMMARY.md
  • Initialize merge log: ./scripts/upstream-merge/log-merge.sh init upstream/main
  • Categorize each change (adopt/adapt/preserve) and document decisions
  • Identify wrapper updates required in code-rs
  • Queue follow-up work items (smoke tests, documentation)

Standing Checks

  • Run cargo build --workspace
  • Run cargo test -p mcp-types
  • Review relevant upstream issues/PRs affecting MCP components
  • Note manual validation required for MCP client/proxy flows (legacy integration suite removed)

Monthly Deep Dive

Performance

  • Benchmark MCP client with large responses (1MB, 2MB, 5MB)
  • Measure proxy latency and throughput
  • Compare performance vs previous month baseline
  • Document any regressions or improvements

Security

  • Run cargo audit on full dependency tree
  • Verify process hardening on all platforms:
    • Linux: cat /proc/$(pgrep code-responses)/status | grep Dumpable
    • macOS: Attempt lldb attach (should fail)
    • Windows: (TODO: Define verification)
  • Review upstream security advisories
  • Check for CVEs in MCP component dependencies

Code Review (Re-Export Model)

  • Review all upstream changes since last month
  • Verify re-export wrappers (code-mcp-client, code-responses-api-proxy, code-process-hardening, code-mcp-types) remain thin/minimal
  • Identify opportunities for code-rs usage patterns to simplify
  • Identify code-rs integration improvements worth contributing upstream
  • Note: Divergence now minimal; focus on ensuring re-exports stay up-to-date

Documentation

  • Update upstream-mcp-reuse-strategy.md with new findings
  • Document any new workarounds or patches needed
  • Review and update implementation guide if API changed
  • Update this checklist with new monitoring needs

Per Upstream Release

Pre-Upgrade

  • Read full changelog for breaking changes
  • Identify deprecated APIs used by code-rs
  • Plan migration for breaking changes
  • Create test branch for upgrade

Testing (Post-Phase 1 Cleanup)

  • Run full build: cargo build --workspace
  • Run minimal test suite: cargo test -p mcp-types -p code-linux-sandbox -p code-cloud-tasks
  • Manual integration validation with real MCP servers (no automated tests currently)
  • Security hardening validation (landlock tests in linux-sandbox)
  • Cross-platform build verification (Linux, macOS, Windows)
  • Note: Full integration test suite removed; rely on build verification and manual validation

Documentation

  • Update dependency versions in docs
  • Document migration steps for breaking changes
  • Update examples if API changed
  • Add release notes to code-rs changelog

Deployment

  • Update Cargo.toml with new version pins
  • Create PR with upgrade changes
  • Run CI/CD pipeline
  • Deploy to staging environment
  • Monitor for issues post-deployment

Critical Alerts (Immediate Action)

Security Advisory

  • Assess impact on code-rs
  • Determine if affected components are used
  • Create hotfix branch if needed
  • Apply patches immediately
  • Notify team of security update
  • Deploy emergency update

Upstream API Breakage

  • Identify affected code in code-rs
  • Assess migration effort
  • Choose mitigation strategy:
    • Pin to last working version (temporary)
    • Implement adapter/wrapper
    • Migrate to new API
    • Fork and maintain (last resort)
  • Create migration plan
  • Execute migration or pin version

Upstream Abandonment

  • Assess recent activity level
  • Contact upstream maintainers
  • Evaluate fork maintenance cost
  • Decision matrix:
    • Wait and monitor (if temporary)
    • Take over maintenance
    • Fork permanently
    • Replace with alternative
  • Document decision and rationale

Quick Commands Reference (Updated for Re-Export Model)

# Check upstream changes
cd codex-rs
git fetch origin
git log origin/main --since="1 week ago" -- mcp-client/ responses-api-proxy/ process-hardening/ mcp-types/

# Verify re-exports build with upstream changes
cd code-rs
cargo build --workspace

# Run minimal test suite
cargo test -p mcp-types
cargo test -p code-linux-sandbox
cargo test -p code-cloud-tasks

# Security audit
cargo audit

# Check process hardening (Linux)
ps aux | grep code-responses
cat /proc/$(pgrep code-responses)/status | grep Dumpable

# Check process hardening (macOS)
ps aux | grep code-responses
lldb -p $(pgrep code-responses)  # Should fail

# Verify re-export wrappers are minimal (no local forks to diff)
# code-mcp-client, code-responses-api-proxy, code-process-hardening, code-mcp-types
# should all be thin re-export wrappers pointing to codex-rs counterparts

GitHub Notifications Setup

  1. Go to: https://github.com/openai/codex-rs
  2. Click "Watch" → "Custom"
  3. Enable notifications for:
    • Issues
    • Pull requests
    • Releases
    • Security alerts
  4. Set up custom rules:
    • Path filter: mcp-client/**
    • Path filter: responses-api-proxy/**
    • Path filter: process-hardening/**
    • Path filter: mcp-types/**

Metrics to Track (Updated for Re-Export Model)

Metric Target Current (2025-10-05) Trend
Upstream divergence (wrapper LOC) <50 ~0 (re-exports only) ✅
Re-export wrapper complexity Minimal Thin wrappers ✅
Build success with latest upstream 100% ✅ —
Security audit issues 0 TBD —
Days since upstream sync check <7 0 —

Note: With re-export model, "divergence" is effectively zero. Focus shifts to monitoring upstream API stability and ensuring wrappers remain minimal.

Contact

Archive

When upstream reuse is complete and stable, archive this checklist with:

  • Final divergence report
  • Lessons learned
  • Recommendations for future component reuse

Last Updated: 2025-10-05 Next Review: 2025-10-12 Model: Re-export wrappers (code-mcp-client, code-responses-api-proxy, code-process-hardening, code-mcp-types all re-export from codex-rs)

Reference in New Issue View Git Blame Copy Permalink