feat(construct-cli): Phase 5 — explore TUI (--format explore)

Adds a ratatui + crossterm interactive browser: Skills/Agents tabs, search (/), navigation, multi-select (Space), and triggers to install selected skills (i) or sync (s); Steelbore-themed. Launched by `--format explore` or a bare invocation on a real terminal; env-gated to fall back to JSON for agents/CI/non-TTY (never traps an agent). After exit the chosen action runs and prints normally. 28 tests, clippy -D warnings, reuse lint, nix build all pass. Completes the planned CLI+TUI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

construct-cli/Cargo.lock

@@ -30,6 +30,7 @@ toml = "0.8"
 # drops the optional `defmt` integration (and its unmaintained transitive deps).
 jiff = { version = "0.2", default-features = false, features = ["std"] }
 owo-colors = "4"
+ratatui = "0.29"
 
 [dev-dependencies]
 assert_cmd = "2"

construct-cli/Cargo.toml

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+//! `construct --format explore` (and a bare TTY invocation): run the [`crate::tui`]
+//! browser, then execute the action it returns once the terminal is restored,
+//! rendering the result as normal human output.
+
+use crate::cli::SyncArgs;
+use crate::commands::{skill, sync};
+use crate::context::Context;
+use crate::install::{self, plan::AddOptions, plan::Scope};
+use crate::output::error::AppError;
+use crate::output::mode::OutputMode;
+use crate::output::{render, CommandOutput};
+use crate::tui::{self, TuiAction};
+
+/// Launch the explore TUI and carry out the chosen action.
+pub(crate) fn run(ctx: &Context) -> Result<Option<CommandOutput>, AppError> {
+    let action = tui::run(ctx)?;
+
+    // The TUI has restored the terminal; render any follow-up as human output.
+    let mut hctx = ctx.clone();
+    hctx.mode = OutputMode::HumanWithColor;
+    hctx.color = true;
+
+    match action {
+        TuiAction::Quit => Ok(None),
+        TuiAction::Sync => {
+            let output = sync::run(&hctx, &SyncArgs { flake_dir: None })?;
+            render::emit(&hctx, &output);
+            Ok(None)
+        }
+        TuiAction::Install(skills) => {
+            let opts = AddOptions {
+                source: install::plan::DEFAULT_SOURCE.to_owned(),
+                skills,
+                agents: Vec::new(),
+                all_agents: false,
+                scope: Scope::Project,
+                copy: false,
+                force: false,
+                refresh: false,
+            };
+            let report = install::add(&hctx, &opts)?;
+            render::emit(&hctx, &skill::report_output(&report));
+            Ok(None)
+        }
+    }
+}

construct-cli/src/commands/explore.rs

@@ -10,23 +10,27 @@
 
 pub(crate) mod agent;
 pub(crate) mod describe;
+pub(crate) mod explore;
 pub(crate) mod schema;
 pub(crate) mod ship;
 pub(crate) mod skill;
 pub(crate) mod sync;
 
-use clap::CommandFactory as _;
-
 use crate::cli::{AgentCommand, Cli, Command, SkillCommand};
 use crate::context::Context;
 use crate::output::error::AppError;
+use crate::output::mode::OutputMode;
 use crate::output::CommandOutput;
 
 /// Route the parsed command to its handler.
 ///
 /// `Ok(Some(output))` is rendered by the caller; `Ok(None)` means the handler
 /// already emitted its own output (help, schema, describe).
 pub(crate) fn dispatch(cli: &Cli, ctx: &Context) -> Result<Option<CommandOutput>, AppError> {
+    // `--format explore` launches the interactive TUI regardless of sub-command.
+    if ctx.mode == OutputMode::Explore {
+        return explore::run(ctx);
+    }
     match &cli.command {
         Some(Command::Skill { verb }) => match verb {
             SkillCommand::Add(args) => skill::add(ctx, args).map(Some),
@@ -51,19 +55,17 @@ pub(crate) fn dispatch(cli: &Cli, ctx: &Context) -> Result<Option<CommandOutput>
             Ok(None)
         }
         None => {
-            no_command(ctx);
-            Ok(None)
+            // A bare invocation on a real terminal opens the explore TUI;
+            // agents and pipelines get the structured capability manifest.
+            if matches!(
+                ctx.mode,
+                OutputMode::HumanWithColor | OutputMode::HumanNoColor
+            ) {
+                explore::run(ctx)
+            } else {
+                let _ = describe::run(ctx, None, None);
+                Ok(None)
+            }
         }
     }
 }
-
-/// Behavior when no sub-command is given. Agents and pipelines get the
-/// structured capability manifest; an interactive user gets help text. (A later
-/// phase replaces the interactive branch with the explore TUI.)
-fn no_command(ctx: &Context) {
-    if ctx.is_machine() {
-        let _ = describe::run(ctx, None, None);
-    } else {
-        let _ = Cli::command().print_long_help();
-    }
-}

construct-cli/src/commands/mod.rs

@@ -153,7 +153,7 @@ pub(crate) fn init(ctx: &Context, args: &InitArgs) -> Result<CommandOutput, AppE
 // ── helpers ───────────────────────────────────────────────────────────────-
 
 /// Wrap an [`InstallReport`] into machine `data` plus a human table.
-fn report_output(report: &InstallReport) -> CommandOutput {
+pub(crate) fn report_output(report: &InstallReport) -> CommandOutput {
     let rows = report
         .items
         .iter()

construct-cli/src/commands/skill.rs

@@ -58,11 +58,6 @@ impl Context {
             absolute_time: g.absolute_time,
         }
     }
-
-    /// True when the resolved mode is one of the machine-readable formats.
-    pub(crate) fn is_machine(&self) -> bool {
-        self.mode.is_machine()
-    }
 }
 
 /// The full command line with `argv[0]` normalized to the canonical binary name

construct-cli/src/context.rs

@@ -32,6 +32,7 @@ mod output;
 mod registry;
 mod sources;
 mod time;
+mod tui;
 
 use std::panic::AssertUnwindSafe;
 

construct-cli/src/main.rs

@@ -57,7 +57,7 @@ pub(crate) fn resolve(g: &GlobalArgs) -> OutputMode {
             FormatArg::Jsonl => OutputMode::Jsonl,
             FormatArg::Yaml => OutputMode::Yaml,
             FormatArg::Csv => OutputMode::Csv,
-            FormatArg::Explore => resolve_explore(g),
+            FormatArg::Explore => resolve_explore(),
         };
     }
 
@@ -78,22 +78,21 @@ pub(crate) fn resolve(g: &GlobalArgs) -> OutputMode {
     }
 }
 
-/// Resolve `--format explore`. The interactive TUI is not yet implemented
-/// (planned for a later phase), so this always falls back — to human output on
-/// an interactive terminal, or to JSON otherwise — and warns on stderr. The
-/// never-trap-an-agent rule (Standard §5) is preserved: agents always get JSON.
-fn resolve_explore(g: &GlobalArgs) -> OutputMode {
-    const REASON: &str = "interactive explore mode is not yet implemented";
-    if is_agent_env() || is_ci() || is_dumb_term() || !std::io::stdout().is_terminal() {
-        warn_tui_fallback(REASON, "json");
+/// Resolve `--format explore`. The interactive TUI runs only on a real
+/// terminal (both stdout and stdin must be TTYs); for agents, CI, dumb
+/// terminals, or pipes it falls back to JSON and warns — never trapping an
+/// agent in a render loop (Standard §5).
+fn resolve_explore() -> OutputMode {
+    if is_agent_env()
+        || is_ci()
+        || is_dumb_term()
+        || !std::io::stdout().is_terminal()
+        || !std::io::stdin().is_terminal()
+    {
+        warn_tui_fallback("no interactive terminal available", "json");
         OutputMode::Json
     } else {
-        warn_tui_fallback(REASON, "human");
-        if should_use_color(g) {
-            OutputMode::HumanWithColor
-        } else {
-            OutputMode::HumanNoColor
-        }
+        OutputMode::Explore
     }
 }