Plan Python and native-process providers before implementation

[Joncallim]

Goal

Plan Python application and native-process providers as read-only runtime-map peers before any implementation work starts.

Plain-English Context

DockerMap already understands Docker and some host services, but many self-hosted machines also run Python apps or ordinary background processes outside Docker. This issue asks an agent to design how DockerMap should recognize those processes safely, without scanning the whole server, exposing secrets, or adding controls that can change the host.

Roadmap Source

• docs/planning/ROADMAP.md -> Not finished -> Python and native-process providers.
• docs/planning/ROADMAP.md -> Next: Read-Only Product Completion -> Runtime Providers -> plan Python and native-process providers as peers under the same read-only runtime map.
• docs/release/RELEASE_CHECKLIST.md -> Execute After Next Commit -> plan Python and native-process providers as the next backend provider peers after the current Rust runtime model and contracts settle.

Recommended Agent

Primary: runtime-provider

Handoff note: involve security-readonly for redaction, process-argument safety, bounded discovery, and no-write guarantees. Involve api-contracts only if the planning pass proposes contract shape changes that need a follow-up issue.

Scope

Planning only for this issue. Do not implement collectors unless the maintainer explicitly redirects.

Target areas:

• docs/planning/ROADMAP.md or a focused provider-planning doc under docs/planning
• docs/security/THREAT_MODEL.md
• docs/testing/TESTING_PLAN.md
• docs/release/RELEASE_CHECKLIST.md if release gates need clearer wording
• .codex/agents/runtime-provider.toml only if the agent scope is missing necessary boundaries

Direction

1. Inspect the existing runtime provider model, current service entity types, and runtime-map contract fixtures.
2. Define what DockerMap should collect for Python apps and native processes, and what it must deliberately avoid.
3. Specify fixed read-only commands or structured data sources. Do not propose user-supplied shell commands.
4. Define hard bounds for filesystem discovery, process inspection, and project-root behavior.
5. Define redaction requirements for env vars, process args, virtualenv paths, package auth config, service files, logs, and inline URLs.
6. Define diagnostics for unavailable tools, permission limits, unsupported platforms, and skipped paths.
7. Propose fixture and test coverage that can run without requiring a real production host.
8. Split any implementation work into narrow follow-up issue suggestions by provider or contract boundary.

Acceptance Criteria

• The plan states the exact data DockerMap should expose for Python apps and native processes.
• The plan states the data DockerMap must not expose, including secrets and sensitive process arguments.
• Discovery is bounded to documented roots, explicit request targets, or hard caps.
• Proposed commands or data reads are fixed and read-only.
• The plan identifies contract, fixture, API, and docs follow-ups as separate task-sized items.
• The plan preserves the invariant that DockerMap does not change files, services, processes, containers, networks, volumes, or host state.

Validation Commands

This is mostly a planning/docs issue. Run or record the narrowest useful checks:

• rg -n "PythonApplication|NativeProcess|runtime map|process|provider|redact|secret" crates packages docs tests
• docs link/path inspection for any changed docs
• npm run test:js only if docs examples or scripts affect tested behavior

State any skipped commands and why.

Closure Evidence

When resolved, post a comment using the repository evidence format:

## Resolution Evidence
- What changed:
- Why this resolves the issue:
- How I checked it:
- Remaining risk or follow-up:

Recommendation: This issue appears resolved and can be closed by a maintainer.

Do not close the issue automatically.

[Joncallim]

Resolution Evidence

• What changed: PR [codex] Document Python and process provider plan #21 added a dedicated Python/native-process provider plan and linked it from the architecture, roadmap, implementation plan, testing plan, threat model, release checklist, and docs index.
• Why this resolves the issue: The plan now states what DockerMap may expose for Python apps and native processes, what it must not expose, the fixed read-only sources it may use, hard discovery caps, redaction rules, diagnostics, fixture expectations, and task-sized follow-ups. It also keeps implementation, API, fixture, docs, and frontend work separate from this planning issue.
• How I checked it: I ran the requested provider-planning search, inspected changed doc links/paths, ran git diff --cached --check, and ran npm run test:js. The PR also passed GitHub TypeScript, Rust, Playwright smoke, and GitGuardian checks before merge.
• Remaining risk or follow-up: No collectors were implemented in this pass. Follow-up work still needs to add fixture-first Python and native-process parsers, API/contract tests, security review, implementation docs, and later frontend runtime-map consumption.

Recommendation: This planning issue appears resolved and can be closed by a maintainer. Leave it open if you want the future collector implementation to stay tracked in the same issue instead of separate follow-up issues.