Complete read-parity file views

[lzehrung]

Summary

• add a public, transport-neutral live file-view API with exact numbered line pagination, whole-file totalLines, continuation offsets, and optional bounded graph context
• expose the same contract through codegraph file, exact-path explore, and MCP get_file, with aligned JSON/pretty output, help, canonical docs, and bundled skill guidance
• keep plain reads live and index-free while confining final real paths to --root

Safety and correctness

• reject binary, NUL-bearing, and malformed UTF-8 raw reads across the complete stream, including bytes outside the selected page
• redact recognized sensitive text configs to bounded structural key summaries; return metadata-only summaries for key material without opening target bytes
• preserve the strongest key-material policy across lexical and final-realpath symlink aliases; explicit raw access still uses normal binary and UTF-8 guards
• reject excessive CLI pagination bounds instead of silently clamping them and publish exact MCP bounds/defaults

Verification

• npm run check
  • lint, formatting, TypeScript build, and native build passed
  • 177 test files passed
  • 2,137 tests passed; 1 skipped
• focused file-view suite: 29 tests passed
• repeated ODW review-and-correct review/fix verification through a final full review
  • final result: 0 confirmed findings, 0 dropped

[Copilot]

Pull request overview

This PR introduces a unified, transport-neutral “live file view” surface that reads current on-disk bytes with bounded line pagination, exact totalLines, continuation via page.nextOffset, and optional opt-in graph context and sensitive-content handling. It wires the same response contract through the agent library API, a new codegraph file CLI command, MCP get_file, and exact-path explore responses, with accompanying tests and documentation.

Changes:

• Added src/agent/fileView.ts implementing bounded line/byte paging, full-stream UTF-8/NUL validation, sensitive redaction/metadata summaries, and optional graph context.
• Exposed the file-view contract via CLI (codegraph file, plus explore flag pass-through), MCP schema/tooling, and public exports (src/index.ts, src/agent.ts).
• Added extensive test coverage and updated canonical docs + bundled skill guidance for the new contract and safety model.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/mcp-server.test.ts	Adds MCP get_file schema checks plus pagination, redaction, and graph-context behavior tests.
tests/file-view.test.ts	New end-to-end suite for file view paging, root confinement, binary/UTF-8 validation, redaction, and key-material handling.
tests/cli-command-modules.test.ts	Verifies codegraph file JSON/pretty output, bounds rejection, graph context, and sensitive handling via dispatcher.
tests/agent-explore.test.ts	Validates explore includes fileView for exact-path queries and updates follow-up command expectations.
src/util/confinedFile.ts	Introduces reusable realpath-based confinement helpers and nearest-existing-path resolution.
src/mcp/tools.ts	Aligns MCP get_file input schema to file-view constants and adds allowSensitive.
src/mcp/server.ts	Routes get_file to the shared agent file-view implementation; updates bounds and request schema.
src/mcp/security.ts	Removes duplicated confinement/read helpers and reuses findNearestExistingPath.
src/index.ts	Exports the new file-view API (functions, constants, and types) from the root package.
src/cli/options.ts	Registers file command schema and adds --offset / --max-bytes value options.
src/cli/help.ts	Adds file command help text and extends explore help to document new explicit flags.
src/cli/file.ts	Implements codegraph file command (JSON default, --pretty formatting, bounds checks).
src/cli/explore.ts	Passes --include-graph-context / --allow-sensitive through to agent explore.
src/cli.ts	Adds CLI routing for the new file command.
src/agent/fileView.ts	Core implementation: bounded paging, exact totalLines, sensitive redaction/metadata, optional graph context.
src/agent/explore.ts	Adds exact-path resolution to include fileView in explore responses and updates follow-ups/pretty output.
src/agent.ts	Re-exports file-view surface from the agent subpath facade.
docs/plans/2026-07-03-07-read-parity-file-view.md	Updates the plan to reflect the implemented multi-surface contract and safety rules.
docs/mcp.md	Documents MCP get_file contract, bounds/defaults, redaction behavior, and exact-path explore fileView.
docs/library-api.md	Documents the library file-view API, request/response fields, and explore fileView behavior.
docs/cli.md	Adds CLI reference and examples for codegraph file and file-view semantics.
docs/agent-workflows.md	Adds workflow guidance for live file reads vs packets and how to opt into graph context/sensitive reads.
codegraph-skill/codegraph/SKILL.md	Updates bundled skill guidance to include live file views and new safety/flag semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.