Skip to main content

4. U1 Summary

The previous articles separately covered the Rust project, the Ink frontend project, and the Rust xtask automation entry point. At this point, we can summarize KQode's first commit-sized unit: U1.

U1 corresponds to U1. Verify the Bun-powered nested Ink package scaffold in the plan document, and it landed in commit 99949b9fe7698a1f0b87acda232281cbaeb4d81d. The goal of this unit was to build scaffolding that makes later development easier: the frontend Ink TUI scaffold, the Rust backend project foundation, and the xtask automation scaffold that unifies development workflows.

What We Have Done So Far​

U1 first changed the repository into a Rust package plus workspace structure. The root Cargo.toml keeps the original KQode runtime package while adding xtask/ to the workspace:

[workspace]
members = [".", "xtask"]
resolver = "3"

This lets the Rust main project and automation commands share one Cargo workspace without prematurely splitting into the future planned multi-crate architecture. U1 only makes the minimal structural change needed at this stage.

On the frontend side, U1 adds the nested tui/ package. It uses Bun for dependency management, Ink + React for terminal rendering, and starts through tui/main.tsx. The current tui/src/App.tsx only displays the KQode version, current workspace cwd, and backend-only preview copy, which is enough to verify the Ink rendering path.

To avoid asking developers to remember commands such as cd tui && bun ..., U1 also adds Cargo-facing TUI automation commands:

cargo xtask tui-install
cargo xtask tui-typecheck
cargo xtask tui-test
cargo xtask tui-dev

These commands are registered in xtask/src/commands/tui/mod.rs, and the implementation reuses xtask/src/support/bun.rs and xtask/src/support/paths.rs. The repository also configures a cargo xtask alias through .cargo/config.toml, so contributors do not need to write the full cargo run -p xtask -- ... command.

U1 also adds a fixture workspace. The commit introduces a minimal tests/fixtures/dummy-react-app/. It is not KQode's own frontend; it provides a more realistic working directory for tui-dev. tui-dev prepares the fixture under target/kqode-test-workspaces/workspace/, then starts the TUI from that workspace cwd, so the UI displays the path of the project being operated on rather than the tui/ package path.

For tests, U1 covers several foundations:

Technical Decisions​

  • Use a nested Bun package for the TUI instead of turning the whole repository into a root JavaScript workspace. KQode's core direction remains Rust-first, and TypeScript is only the UI surface. Keeping the frontend under tui/ lets the Ink project use the right toolchain without letting package-manager configuration take over the repository root.

  • Expose Cargo-facing commands to contributors. Even if the implementation uses Bun, tsx, Vitest, or Vite fixtures, the daily entry point remains:

    cargo xtask ...

    This lets docs, IDE run profiles, CI, and local command lines reuse the same automation commands. If the underlying tools change later, only the xtask implementation needs to change.

  • Start tui-dev from the workspace cwd rather than from the tui/ directory. A Coding Agent serves the user's current project, not its own UI package. Even when the UI only displays a few lines, the cwd semantics need to be correct first; otherwise, file references, Git status, tool execution, and approvals would require rework later.

  • Treat fixtures as read-only seeds and run against ignored workspaces under target/. The committed dummy React app provides a reproducible initial state, but tests and manual runs do not mutate the fixture source directory. This keeps fixtures stable and lets every run start from a fresh workspace.