grove core grove core

Grove Core

core is the foundational Go library and debugging interface for the Grove ecosystem. It provides shared infrastructure for configuration management, workspace discovery, logging, and terminal user interface (TUI) components, ensuring consistency across all Grove CLI tools.

Core Mechanisms

Layered Configuration: Configuration is loaded and merged from multiple sources in a specific precedence order:

  1. Global: ~/.config/grove/grove.yml (System-wide defaults and search paths).
  2. Ecosystem: grove.yml in a parent directory defining a workspace boundary.
  3. Project: grove.yml in the current working directory.
  4. Overrides: grove.override.yml for local, git-ignored developer settings.

Workspace Discovery: The DiscoveryService scans directories defined in the groves configuration. It classifies filesystem locations into three types based on file markers:

  • Ecosystems: Directories containing a grove.yml with a workspaces key.
  • Projects: Directories containing a grove.yml or .git directory.
  • Worktrees: Git worktrees located in .grove-worktrees/ directories.

Unified Logging: The logging system writes two streams simultaneously:

  • Structured: JSON-formatted logs written to .grove/logs/ in the workspace root for machine analysis.
  • Human-Readable: Styled, colored text written to stderr for interactive use.
  • Filtering: Supports component-based filtering rules defined in grove.yml (e.g., hiding debug logs from specific subsystems).

State Daemon: A background process (groved) maintains an in-memory cache of the ecosystem state. It uses file system watchers (fsnotify) to track changes in real-time, reducing the overhead of repetitive disk scanning for tools like nav and hooks.

Packages

Application Infrastructure

  • cli: Wraps spf13/cobra to provide standard flags (--json, --verbose, --config) and styled help output.
  • config: Handles YAML parsing, environment variable expansion (${VAR}), and JSON schema validation.
  • logging: A wrapper around logrus providing the unified logging streams and component registry.
  • daemon: Client/Server architecture for the state cache, supporting both direct library calls and RPC over Unix sockets.

System Integration

  • pkg/tmux: A client for controlling tmux servers. Manages sessions, windows, and panes via the CLI or socket.
  • git: Wrappers for git operations, specifically focusing on worktree management, branch detection, and status retrieval.
  • command: A safe command executor that validates arguments and handles timeouts.

TUI Components

The tui package provides reusable Bubble Tea components:

  • navigator: A list-based browser for selecting projects or files.
  • logviewer: A component for tailing files and streaming logs with scrollback and filtering.
  • jsontree: An interactive viewer for exploring structured JSON data.
  • theme: Centralized color palette and style definitions (Kanagawa, Gruvbox).

The core CLI

While primarily a library, this repository compiles to a core binary used for debugging the ecosystem state and running the daemon.

  • core ws: Interactive TUI for exploring the discovered workspace hierarchy.
  • core logs: Aggregates and streams logs from .grove/logs/. Supports filtering by component.
  • core config-layers: Prints the merged configuration and the source file for each value.
  • core groved: Manages the background daemon process (start, stop, status, monitor).

See the documentation for detailed usage instructions: