Skip to content

PLAN.md

Latest commit

 

History

History
139 lines (94 loc) · 7.75 KB

PLAN.md

File metadata and controls

139 lines (94 loc) · 7.75 KB

Backend Overhaul — Controller Registry Consolidation

Branch: feat/backend-overhaul Base: main @ 515c4f4b

Why

Project rule (CLAUDE.md): domain functionality exposed to CLI + JSON-RPC only via the controller registry (schemas.rs per domain + src/core/all.rs). Current state is 90% there — 34 domains fully migrated — but six CLI adapters and one JSON-RPC fallback still live in the transport layer. Finishing this lets us delete ~95KB of adapter code and enforce the rule with a lint/grep check.

Goals

  1. Zero domain-specific code in src/core/cli.rs, src/core/jsonrpc.rs, src/rpc/dispatch.rs.
  2. Every CLI command and JSON-RPC method dispatched through the shared registry.
  3. No behavior change — all existing CLI flags and RPC methods preserve names, params, outputs.
  4. Unregistered infrastructure modules documented as intentionally transport-agnostic.

Non-goals

  • No new domain functionality.
  • No changes to skills QuickJS runtime exposure (stays runtime-only).
  • No renames of existing CLI flags or RPC method names.
  • No touching memory-tree domain (sanil-23 has in-flight PRs #732 #733).

Current leakage

File LOC What's there Target
src/core/agent_cli.rs 21.4K agent CLI adapter openhuman/agent/schemas.rs
src/core/memory_cli.rs 15.3K memory CLI adapter openhuman/memory/schemas.rs
src/core/text_input_cli.rs 12.4K text_input CLI adapter openhuman/text_input/schemas.rs
src/core/screen_intelligence_cli.rs 26.5K screen_intelligence CLI adapter openhuman/screen_intelligence/schemas.rs
src/core/tree_summarizer_cli.rs 13.2K tree_summarizer CLI adapter openhuman/tree_summarizer/schemas.rs
src/core/cli.rs (voice block) ~2K run_voice_server_command() openhuman/voice/schemas.rs
src/rpc/dispatch.rs 76 openhuman.security_policy_info fallback openhuman/security/schemas.rs (or about_app)

Total: ~95KB of adapter code to fold into registry.

Exposure rule (decision tree)

Two legitimate shapes for exposing a domain capability. Pick by command shape, not by convenience:

  1. Controller registry (src/openhuman/<domain>/schemas.rs + src/core/all.rs). Use for request/response RPC-style capabilities — take params, do work, return JSON, done. The vast majority of domain methods. CLI access is free via the generic namespace dispatcher (openhuman <domain> <verb> --args).

  2. Domain-owned CLI adapter (src/openhuman/<domain>/cli.rs). Use only for standalone long-running / blocking operational commands — e.g. openhuman voice runs a hotkey listener forever, holds the process, logs to stderr. These don't fit the registry's fire-and-return JSON contract. The adapter lives inside the domain (not in src/core/cli.rs) so transport layer stays generic.

Hard rule: no domain-specific imports or logic in src/core/cli.rs, src/core/jsonrpc.rs, or src/rpc/dispatch.rs. The only allowed reference is the dispatch line that routes args[0] to the domain's CLI function. Everything else lives in the domain.

Don't invent a third shape. If a capability feels like it needs one, it probably belongs in one of the two above with a thin adjustment.

Approach

Each migration is a self-contained diff:

  1. Confirm domain already has schemas.rs with all_<domain>_registered_controllers().
  2. For each CLI subcommand in <domain>_cli.rs:
    • Identify the underlying domain function it calls.
    • Add a handle_<verb> fn in schemas.rs that takes Map<String, Value> and returns ControllerFuture.
    • Register it in all_<domain>_registered_controllers().
  3. Delete the <domain>_cli.rs file.
  4. Remove its import from src/core/cli.rs / mod.rs.
  5. Verify CLI flags still work via generic dispatcher — the registry already exposes them by method name.
  6. cargo check + cargo test -p openhuman per step.

The generic CLI adapter in cli.rs already knows how to route <domain> <verb> --key value to registry method openhuman.<domain>_<verb>. Migration is mostly deletion once handlers exist.

Phases

Phase 1 — Smallest adapter first (shakedown)

voice (~2K inline in cli.rs). Lowest risk: one server command, confirms the approach end-to-end before touching bigger files.

  • Commit: refactor(voice): move CLI adapter to controller registry

Phase 2 — Mechanical migrations (one PR each)

Order = smallest file first, so each PR is reviewable and CI catches issues early.

  1. text_input (12.4K) — likely thin wrappers.
  2. tree_summarizer (13.2K).
  3. memory_cli (15.3K) — coordinate with sanil-23 memory-tree PRs; rebase after #732/#733 merge or pair-review.
  4. agent_cli (21.4K).
  5. screen_intelligence (26.5K) — largest, leave for last.

Each: one commit, one PR, self-contained. No bundling.

Phase 3 — JSON-RPC dispatch fallback

Move openhuman.security_policy_info from src/rpc/dispatch.rs into whichever domain owns security policy (likely about_app or a new security module). Delete rpc/dispatch.rs if it becomes empty, else leave as a thin generic dispatch shim.

Phase 4 — Enforce the rule

Add a build-time check or CI grep. The rule must forbid domain imports/types in the transport layer while still allowing the dispatcher to call the generic ::cli::run_* entrypoints that live inside each domain:

# Forbid `use crate::openhuman::<domain>::…` imports in transport files.
! grep -rE '^\s*use\s+crate::openhuman::[a-z_]+::' \
    src/core/cli.rs src/core/jsonrpc.rs src/rpc/dispatch.rs

# Forbid any other domain reference that is NOT a call into ::cli::run_*(…).
# (The dispatcher is allowed to invoke `crate::openhuman::<domain>::cli::run_<x>(...)`.)
! grep -rE 'crate::openhuman::[a-z_]+::' \
    src/core/cli.rs src/core/jsonrpc.rs src/rpc/dispatch.rs \
  | grep -vE 'crate::openhuman::[a-z_]+::cli::run_[a-z_]+\('

Fails if any domain-specific import or non-dispatcher reference creeps back in. Commit as chore(core): fence domain imports out of transport layer.

Phase 5 — Document unregistered modules

Add a short table to CLAUDE.md listing intentionally-unregistered infra modules (accessibility, approval, context, embeddings, integrations, node_runtime, overlay, providers, routing, tokenjuice, tool_timeout) with one-liner "why not in registry" for each. Also document skills as runtime-only.

Risks

  • agent_cli / screen_intelligence size — large files may hide subtle flag-parsing logic not obvious from a first read. Mitigation: test-drive each CLI subcommand manually after migration; add CLI smoke tests to the registry dispatcher if missing.
  • memory_cli collision with sanil-23 — memory-tree PRs touch adjacent paths. Mitigation: do phase 2.3 last, rebase on top of merged PRs.
  • CLI flag drift — generic adapter parses flags by schema. If current _cli.rs does custom parsing (e.g. positional args, subcommand nesting), need to extend schema before deleting. Mitigation: read each CLI file top-to-bottom before writing handler.
  • Behavior diff at registry boundary — registry handlers return ControllerFuture with JSON; _cli.rs may print formatted text. Mitigation: keep a thin formatter in the generic CLI path, not per-domain.

Verification per step

cargo check --manifest-path Cargo.toml
cargo test -p openhuman --test json_rpc_e2e
# Manual CLI smoke for migrated domain:
./target/debug/openhuman <domain> <verb> --args...

Plus pnpm test:rust for the full mock-backed integration suite before each PR.

Milestones

  • M1: Phase 1 done, shakedown merged.
  • M2: Phases 2.1–2.5 done, all *_cli.rs deleted.
  • M3: Phase 3 done, rpc/dispatch.rs cleaned.
  • M4: Phase 4+5 done, rule enforced, docs updated.

Estimate: M1 = 0.5d, M2 = 3–4d (one domain/day), M3 = 0.5d, M4 = 0.5d. Total ~1 week of focused work.