cli: Instructions file for Codex

mcpm contributor instructions

mcpm is the open-source, CLI-first MCP security guard and package manager: npm @getmcpm/cli, command mcpm. Trust assessment, supply-chain evidence and runtime protection are the product. Keep changes small, deterministic and scoped.

Start here

• Read CONTRIBUTING.md for setup and checks, and docs/MAINTAINER-WORKFLOW.md for current context, task skills and historical decisions. Read detailed references only as needed.
• docs/BACKLOG.md is the selected active queue. Its #IDs are project backlog IDs, not GitHub issues. Research and historical roadmaps are context, not authorization or commitments to build the whole queue.
• Follow the user's scope and builder/reviewer choices. Use existing authorization and finish authorized work autonomously; ask only for missing material scope or permission. Review-only requests stay read-only. A build or PR does not imply authorization to merge, tag, publish, deploy or contact other people.
• Preserve dirty worktrees, unrelated files and local history. Use isolated checkouts when needed; never reset or restore another contributor's work.

Product and implementation invariants

• Local-first, OSS-first, no telemetry, hosted backend, proprietary lock-in or additional model/subscription requirement on the default path. Calling agents handle natural language; mcpm supplies deterministic evidence. Jev/Clef is deferred, not a dependency. Avoid new runtime dependencies; justify any needed.
• One TypeScript/ESM package, Commander CLI, Zod boundary schemas, tsup build, Vitest tests. Reuse existing helpers and immutable data patterns; return new objects rather than mutate shared data. Consume official Registry API v0.1 at registry.modelcontextprotocol.io; tolerate upstream errors/resets honestly.
• Local state lives in ~/.mcpm/; registry reads are live, with no registry cache. Do not introduce infrastructure for speculative future roadmap features.
• Validate registry/config/tool input before use. Preserve security/trust gates, strict MCP inputs, native restrictions and explicit coverage gaps. Never lower thresholds, allow unguarded/fresh launches or re-lock drift merely to finish.
• Config writes use backup-before-write and atomic write-then-rename. Preserve unrelated entries/bytes, credentials, custom arguments, disabled state and guard/confinement wrappers. Respect client-specific adapters (including VS Code JSONC and Cursor/Gemini parked definitions); unreadable is not absent/healthy.
• Keep values out of secret findings/reports/logs. Use disposable state for tests; do not read real client configuration or touch a real keychain for a fixture.
• The external scanner is opt-in via an already-installed executable named by MCPM_EXTERNAL_SCANNER; never fetch one automatically or bypass runner/shell refusal. Native safety floors exclude unverifiable external-scanner credit.
• Guard is a stdio relay; HTTP/SSE does not gain its protection. OS confinement is opt-in and macOS-first with documented hybrid/fail-closed conditions; do not turn it into a claim of universal sandboxing or general exfiltration prevention.
• Unkeyed integrity sidecars detect corruption, not authenticity against a same-user writer. Sigstore authenticates build identity, not code safety.