Centralize CLI and adapter access through the API facade - #50
Merged
Conversation
Rename the command materialization module so repository tooling and architecture scanners do not classify tracked source as generated build output. The module contents remain unchanged; only Rust module references move with it. Constraint: Scryer excludes build-output paths from completeness accounting Rejected: Add synthetic anchors around the filtered path | would hide the source-discovery mismatch Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep product source modules out of directories named like generated build outputs Tested: cargo fmt --all --check; cargo test --workspace; cargo clippy --workspace --all-targets --all-features -- -D warnings; Scryer validate_model and get_health Not-tested: None
Centralize CLI, MCP, lifecycle, refresh, and embedded execution behind a transport-neutral registry and facade. Linearize materialization from scanned source snapshots through planning, enrichment, and the sole graph writer while preserving existing outputs and behavior. Constraint: Preserve CLI flags, MCP tool schemas, block output, exit codes, and graph semantics Rejected: Retain direct adapter-to-service calls | would leave duplicate execution paths Confidence: high Scope-risk: broad Reversibility: clean Directive: Register future operations in OperationRegistry and route adapters through CodebaseGraphApi Tested: cargo fmt --check; cargo clippy --all-targets --all-features -- -D warnings; cargo test --all-targets --all-features; Scryer validation and drift reconciliation Not-tested: Peak-memory comparison for large repositories
Move request normalization, repository runtime resolution, materialization preparation, refresh coordination, graph reads, lifecycle work, and shared presentation behind the API boundary. Reduce CLI and MCP modules to parsing, public invocation, and response framing. Constraint: Preserve existing CLI flags, MCP tool contracts, result shapes, and storage formats Rejected: Retain CLI compatibility wrappers | would preserve reverse dependencies and duplicated policy Confidence: high Scope-risk: broad Reversibility: clean Directive: Keep src/api free of crate::cli imports and route new transport behavior through public contracts Tested: cargo fmt --check; cargo clippy --all-targets --all-features -- -D warnings; cargo test --all-targets --all-features Not-tested: none
Record the verified gap analysis between OKF v0.1, the current Markdown materializer, and the transport-neutral public API. Recommend an adjacent OKF projection so wiki semantics can evolve without destabilizing code graph contracts. Constraint: Preserve the existing CodebaseGraphApi and graph schema contracts Rejected: Reuse DocumentationSource and DocumentationChunk as the canonical OKF model | those nodes omit frontmatter, reserved files, links, and concept identity Confidence: high Scope-risk: narrow Directive: Keep OKF page semantics separate from graph-search response contracts until the normalized model stabilizes Tested: Source-reference review and git diff --cached --check Not-tested: No production code changed; runtime tests not applicable
Place command and MCP transports under peer src/adapters modules while preserving the existing CLI compatibility export. Move MCP-owned protocol constants, HTTP session state, refresh wiring, and response framing out of the CLI adapter. Constraint: Preserve CLI commands, MCP stdio and HTTP behavior, public result shapes, and the codebase_graph::cli compatibility path Rejected: Keep MCP nested under CLI | contradicts the peer transport boundary and permits reverse adapter dependencies Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep MCP independent of adapters::cli; CLI may launch MCP only through adapters::mcp Tested: cargo fmt --all -- --check; cargo clippy --all-targets --all-features -- -D warnings; cargo test --all-targets --all-features --quiet; cargo test -p xtask --quiet; cargo test mcp -- --nocapture; cargo test api::boundary_tests -- --nocapture Not-tested: none
Route standalone MCP registration through the public API so transport adapters only parse requests, frame verification, and print responses. Remove the duplicate CLI descriptor, rendering, client metadata, filesystem, and repository-resolution implementations. Constraint: Preserve existing CLI install payloads and optional post-install verification. Rejected: Share private CLI helpers with the API | keeps product policy owned by a transport adapter. Confidence: high Scope-risk: moderate Directive: Keep supported-client policy and installation mutation under src/api. Tested: cargo test --all-targets; cargo clippy --all-targets -- -D warnings; cargo fmt -- --check Not-tested: Native Codex, Claude, and OpenClaw installer executables were not invoked.
Move registered invocation preparation, canonical defaults, MCP operation lookup, and refresh-safe graph reads behind the public API facade. MCP now parses transport fields and frames responses without constructing product requests or selecting read-lock policy. Constraint: Preserve existing MCP JSON-RPC schemas and response framing. Rejected: Keep hardcoded MCP dispatch with shared constants | operation aliases and refresh policy would still drift across boundaries. Confidence: high Scope-risk: moderate Directive: Keep product request defaults and refresh consistency policy under src/api. Tested: cargo test --all-targets --all-features; cargo clippy --all-targets --all-features -- -D warnings; cargo fmt --all -- --check Not-tested: External third-party MCP client interoperability beyond repository stdio and HTTP suites.
Route CLI and MCP product behavior through CodebaseGraphApi, move process transport selection into a bootstrap boundary, and expose refresh watch data as public API contracts. Extract shared command request mapping so build and watch adapters do not depend on sibling behavior. Constraint: Transport adapters may consume public API contract types but must not import API implementation modules. Rejected: Expose refresh and materialization internals through root re-exports | preserves hidden coupling instead of enforcing the facade boundary Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep production adapter behavior behind CodebaseGraphApi and extend boundary_tests.rs when adding a new interface path. Tested: cargo test; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo fmt --all -- --check; Scryer validation, health, pending, and drift checks Not-tested: Manual long-running MCP HTTP server session outside automated coverage
The prebuilt lbug archive exposes HTTPFS OpenSSL symbols without its transitive linker requirements. CI now supplies those requirements on Linux and provisions static Windows aliases that match lbug's expected names. Constraint: lbug 0.17.1 prebuilt archives omit OpenSSL link metadata Rejected: Upgrade to lbug 0.18.3 | its existing CI run still fails on Windows and macos-15-intel Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep the OpenSSL aliases synchronized with lbug's ssl/crypto linker names Tested: cargo fmt --check; cargo test --workspace --locked; cargo clippy --workspace --all-targets --all-features --locked -- -D warnings; YAML parse; git diff --check Not-tested: GitHub-hosted Linux and Windows runners
The lbug build script downloaded its latest Linux archive, whose embedded extension metadata requested JSON from an incompatible v0.19.0 endpoint. Linux test and package jobs now fetch the v0.17.1 compatibility archive that matches Cargo.lock, as the macOS jobs already do. Constraint: lbug 0.17.1 defaults to a moving latest prebuilt archive on Linux Rejected: Change the smoke test to avoid JSON | it would conceal the release artifact incompatibility Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep every prebuilt lbug archive pinned to the version recorded in Cargo.lock Tested: release asset contents; cargo fmt --check; cargo test --workspace --locked; cargo clippy --workspace --all-targets --all-features --locked -- -D warnings; YAML parse; git diff --check Not-tested: GitHub-hosted Linux and Windows runners
Record the Scryer-backed architecture and phased implementation contract for a complete read-only OKF wiki. Keep OKF semantics, projection state, and transports in an adjacent workspace package while composing code context only through CodebaseGraphApi. Constraint: Existing graph public requests, MCP names, and .codebaseGraph state must remain backward compatible Rejected: Reuse DocumentationSource nodes as canonical OKF concepts | the current materializer omits frontmatter, reserved-file, identity, and link semantics Rejected: Include browser authoring in the first subsystem | authoring requires a separate trust and Git-governance boundary Confidence: high Scope-risk: broad Directive: Implement Scryer change chg-1 phase by phase and attach tests before folding each condition-shaped responsibility Tested: Scryer structural validation and git diff --cached --check Not-tested: No production implementation exists yet; runtime verification is specified in the plan
Keep Developer or Agent as the sole person in the wiki architecture and make the existing person-to-system relationship explicit across the Scryer plan and implementation document. Constraint: Persons connect to the software system at the system-context level. Rejected: Retain a separate Knowledge Reader persona | the approved actor model uses Developer or Agent only Confidence: high Scope-risk: narrow Reversibility: clean Tested: Scryer structural validation; pending-plan inspection; markdown diff check Not-tested: Production code, because this change only corrects the implementation plan
Record Knowledge Wiki as the exact user-facing MCP server name while keeping internal package and tool identifiers independent. Constraint: MCP clients must display the server as Knowledge Wiki Confidence: high Scope-risk: narrow Reversibility: clean Tested: Scryer structural validation; markdown diff check Not-tested: Production code, because implementation has not started
The Windows package job downloaded LadybugDB's moving latest static library, whose extension metadata requested JSON from an unavailable v0.19.0 endpoint. Pinning the archive to Cargo.lock keeps the runtime and extension protocol aligned. Constraint: The v0.17.1 Windows release asset is a ZIP that exports lbug.lib Rejected: Leave automatic lbug download enabled | it retrieves the latest release and causes an extension-version mismatch Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep static lbug assets tied to Cargo.lock across every CI platform Tested: cargo fmt --check; CI YAML matrix validation; cargo test --workspace --locked; cargo clippy --workspace --all-targets --all-features --locked -- -D warnings Not-tested: GitHub-hosted Windows runner package smoke test
Constrain the initial Knowledge Wiki MCP surface to five read-only tools and record their exact user-facing display labels. Constraint: Public MCP metadata must match the approved identifiers and labels exactly Rejected: Advertise directory, neighborhood, and recent-change tools initially | they were not included in the approved public catalog Confidence: high Scope-risk: narrow Reversibility: clean Tested: Scryer structural validation; model readback; markdown diff check Not-tested: Production code, because implementation has not started
Restore the full read-tool catalog and extend Knowledge Wiki with bounded MCP operations for creating bundles, creating pages, and populating page content. Constraint: Authoring is limited to configured OKF roots and typed wiki operations Rejected: Direct writes from the MCP adapter | bypasses validation, conflict detection, and the public API boundary Rejected: Remove directory, neighborhood, and recent-change tools | the earlier removal was an incorrect inference from display-name mappings Confidence: high Scope-risk: broad Reversibility: clean Tested: Scryer structural validation; chg-2 pending-plan inspection; markdown diff check Not-tested: Production code, because implementation has not started
Align the planned wiki package boundary and generated-state root with the approved crates/k-wiki and .kWiki names. Constraint: The Cargo package and binary names remain unchanged Confidence: high Scope-risk: narrow Reversibility: clean Tested: Scryer structural validation; boundary readback; stale-name search; markdown diff check Not-tested: Production code, because implementation has not started
The prebuilt archive was extracted successfully, but Git Bash exported its MSYS path to the MSVC build. Converting only the Windows environment value lets cl.exe resolve lbug.h while preserving Unix paths. Constraint: Archive preparation runs in Git Bash while the Rust C++ bridge compiles with MSVC Rejected: Disable the pinned Windows archive | that restores the incompatible moving LadybugDB release Confidence: high Scope-risk: narrow Reversibility: clean Directive: Convert Bash paths before exposing native-toolchain include or library directories on Windows Tested: CI YAML path-conversion validation; cargo fmt --check; cargo test --workspace --locked; cargo clippy --workspace --all-targets --all-features --locked -- -D warnings Not-tested: GitHub-hosted Windows runner
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Testing