ruvnet--RuView/harness/homecore/README.md

Homecore metaharness

homecore is the developer-facing metaharness for RuView's native Rust Homecore stack. Its package contract is:

npx homecore

The harness maps current capabilities to source and validation commands, exposes a bounded MCP server, and can delegate repository exploration to a locally installed Claude Code or Codex CLI. It does not start a home server, change configuration, migrate data, or publish code by itself.

Commands

# Source-cited overview; this is the default command.
homecore guidance
homecore guidance --topic plugins --query "Wasmtime signatures"
homecore capabilities

# Diagnose the package, WASM kernel, local CLIs, and optional checkout.
homecore doctor --repo .
homecore wasm status --strict

# Run focused Homecore tests in a trusted RuView checkout.
homecore verify --repo . --profile core
homecore verify --repo . --profile wasm
homecore verify --repo . --profile hap

# Explore through a local host. Both are read-only by default.
homecore agent run --host codex --repo . --prompt "Map startup restore"
homecore agent run --host claude-code --repo . --prompt "Review plugin trust"

# Start the stdio MCP server.
homecore mcp start

# Search or verify reviewed shared knowledge.
homecore brain search --query "REST WebSocket compatibility"
homecore brain verify --repo .

Workspace-writing host runs require both --allow-write and --confirm. The harness never emits permission-bypass flags. Every MCP tool is read-only; Cargo verification remains an explicit local CLI operation and is not exposed through MCP. MCP request size, queue depth, tool-call duration, and the total tool-call budget of each server process are bounded.

Repository-aware MCP calls are bound to the exact RuView checkout found when the server starts. Launch it from that checkout, or set HOMECORE_TRUSTED_REPO to its root. An MCP request cannot nominate a different checkout as its own trust anchor.

The packaged .codex, .claude, and generic MCP templates invoke an already-installed homecore binary and never track an npm dist-tag. To print configuration for an ephemeral installation, run homecore install --host codex or homecore install --host claude-code; the generated npx configuration pins the package's exact version.

WASM-first runtime

The harness asks @metaharness/kernel for its packaged WebAssembly backend before considering a native or JavaScript fallback. The kernel validates the MCP server specification. homecore wasm status reports the backend that actually loaded; --strict fails if it is not WASM.

This is separate from Homecore's application plugin boundary:

• compiled-in native plugins must be explicitly registered in the server;
• external plugin packages are bounded and signature-checked WebAssembly;
• execution through Wasmtime is feature-gated;
• arbitrary native dynamic libraries are not loaded.

Use homecore verify --profile wasm to exercise the Wasmtime-specific Rust tests in a checkout.

Capability honesty

The catalog distinguishes implemented, feature-gated, provider-required, and integration-dependent behavior. Home Assistant compatibility means the documented core REST/WebSocket contract, not every endpoint supplied by the Home Assistant integration ecosystem. HAP protocol tests are not Apple certification. STT/TTS provider contracts do not imply that a deployment has a real speech provider.

Every guidance result cites repository paths, focused validation commands, and known limitations. A packaged citation is navigation evidence; source, tests, accepted ADRs, and repository policy remain authoritative.

Shared brain

Reviewed records live in brain/corpus/core.jsonl. Search is deterministic and local. brain propose prints an unreviewed JSONL candidate but never edits the canonical corpus. Retrieved text cannot grant authority, change tool policy, or override repository instructions. Private indexes and raw transcripts are never packaged.

Development

npm install --ignore-scripts
npm test
npm run test:security
npm run brain:verify -- --repo ../..
npm run manifest:update
npm run manifest:verify
npm audit --omit=optional
npm pack --dry-run

Release is CI-only with npm provenance. Do not publish from a workstation.

Architecture

ADR-285 defines this harness. It builds on the Homecore master decision (ADR-126), the plugin and API boundaries (ADR-128 and ADR-130), the server security review (ADR-161), the migration contract (ADR-165), and the existing RuView metaharness and npm distribution decisions (ADR-182, ADR-263, ADR-265).