mirror of
https://github.com/ruvnet/RuView
synced 2026-08-11 20:41:44 +00:00
feat(homecore): add WASM-first developer metaharness (#1477)
Adds the accepted ADR-285 Homecore metaharness, WASM-first kernel, read-only MCP guidance, guarded local host adapters, reviewed memory, and provenance-only npm release gates.
This commit is contained in:
rUv
@@ -0,0 +1,119 @@
|
||||
# Homecore metaharness
|
||||
|
||||
`homecore` is the developer-facing metaharness for RuView's native Rust
|
||||
Homecore stack. Its package contract is:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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).
|
||||
Reference in New Issue
Block a user