Skip to content

refactor: show beta notices whenever stderr is a terminal #336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
socksy wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

refactor: show beta notices whenever stderr is a terminal #336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 6 additions & 39 deletions crates/tower-cmd/src/beta.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
use std::io::{self, IsTerminal};

use tower_telemetry::debug;

use crate::output::{self, Out};
use crate::output;

pub(crate) struct BetaFeature {
id: &'static str,
Expand All @@ -21,6 +17,10 @@ impl BetaFeature {
None => self.message.to_string(),
}
}

pub fn notify_once(&self) {
output::notice_once(self.id, "Beta:", &self.notice());
}
}

pub(crate) const STORAGE_BETA_MESSAGE: &str = "Tower Storage is in beta. Core functionality is stable, but some featues and interfaces might change before general availability.";
Expand All @@ -31,30 +31,9 @@ pub(crate) const STORAGE: BetaFeature = BetaFeature {
docs_url: None,
};

pub(crate) fn notify_once(out: &Out, feature: &BetaFeature) {
let stderr_is_terminal = io::stderr().is_terminal();

if !should_notify(out.interactive(), out.foreground(), stderr_is_terminal) {
return;
}

match config::claim_notice(feature.id) {
Ok(true) => output::notice_to_stderr("Beta:", &feature.notice()),
Ok(false) => {}
Err(err) => debug!("Failed to persist CLI notice {}: {}", feature.id, err),
}
}

/// The notice only goes out for a foreground CLI driving an interactive terminal:
/// human output on a stdout TTY (never JSON or MCP capture), with stderr also a
/// TTY so the notice itself is seen.
fn should_notify(interactive: bool, foreground: bool, stderr_is_terminal: bool) -> bool {
interactive && foreground && stderr_is_terminal
}

#[cfg(test)]
mod tests {
use super::{should_notify, BetaFeature, STORAGE, STORAGE_BETA_MESSAGE};
use super::{BetaFeature, STORAGE, STORAGE_BETA_MESSAGE};

#[test]
fn short_about_has_one_beta_suffix() {
Expand Down Expand Up @@ -85,16 +64,4 @@ mod tests {
"Example is in beta. Its interface may change. Learn more: https://example.com/beta"
);
}

#[test]
fn notice_requires_interactive_foreground_and_stderr_terminal() {
assert!(should_notify(true, true, true));
// stdout not an interactive terminal (redirected, JSON, or MCP capture)
assert!(!should_notify(false, true, true));
// not a foreground CLI (MCP or discarded output)
assert!(!should_notify(true, false, true));
// stderr not a terminal
assert!(!should_notify(true, true, false));
assert!(!should_notify(false, false, false));
}
}
16 changes: 8 additions & 8 deletions crates/tower-cmd/src/catalogs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ pub async fn do_list(out: &output::Out, config: Config, args: &ArgMatches) {
};

if is_storage_catalog_type(catalog_type) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();
}

let catalogs = out
Expand Down Expand Up @@ -214,7 +214,7 @@ pub async fn do_list(out: &output::Out, config: Config, args: &ArgMatches) {
}

pub async fn do_credentials(out: &output::Out, config: Config, args: &ArgMatches) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();

let name = args
.get_one::<String>("catalog_name")
Expand Down Expand Up @@ -263,7 +263,7 @@ pub async fn do_show(out: &output::Out, config: Config, args: &ArgMatches) {

let is_storage = is_storage_catalog_type(Some(&response.catalog.r#type));
if is_storage {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();
}

let tables = if is_storage {
Expand Down Expand Up @@ -464,7 +464,7 @@ fn redact_token(message: &str, token: &str) -> String {
}

pub async fn do_query(out: &output::Out, config: Config, args: &ArgMatches) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();

let name = args
.get_one::<String>("catalog_name")
Expand Down Expand Up @@ -1550,7 +1550,7 @@ fn knowledge_cmd() -> Command {
}

pub async fn do_knowledge_list(out: &output::Out, config: Config, args: &ArgMatches) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();

let catalog = args
.get_one::<String>("catalog_name")
Expand Down Expand Up @@ -1587,7 +1587,7 @@ pub async fn do_knowledge_list(out: &output::Out, config: Config, args: &ArgMatc
}

pub async fn do_knowledge_show(out: &output::Out, config: Config, args: &ArgMatches) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();

let catalog = args
.get_one::<String>("catalog_name")
Expand All @@ -1609,7 +1609,7 @@ pub async fn do_knowledge_show(out: &output::Out, config: Config, args: &ArgMatc
}

pub async fn do_knowledge_set(out: &output::Out, config: Config, args: &ArgMatches) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();

let catalog = args
.get_one::<String>("catalog_name")
Expand Down Expand Up @@ -1657,7 +1657,7 @@ pub async fn do_knowledge_set(out: &output::Out, config: Config, args: &ArgMatch
}

pub async fn do_knowledge_delete(out: &output::Out, config: Config, args: &ArgMatches) {
beta::notify_once(out, &beta::STORAGE);
beta::STORAGE.notify_once();

let catalog = args
.get_one::<String>("catalog_name")
Expand Down
17 changes: 16 additions & 1 deletion crates/tower-cmd/src/output.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -616,8 +616,23 @@ pub fn background_error(msg: &str) {
write_to_stderr(&format!("{} {}\n", "Oh no!".red(), msg));
}

/// Writes a labelled notice to stderr once per user, ever. The once-per-user
/// claim is only spent when stderr is a terminal, so a script, MCP capture, or
/// CI run can't use it up on a notice nobody saw.
pub(crate) fn notice_once(id: &str, label: &str, msg: &str) {
if !io::stderr().is_terminal() {
return;
}

match config::claim_notice(id) {
Ok(true) => notice_to_stderr(label, msg),
Ok(false) => {}
Err(err) => debug!("Failed to persist CLI notice {}: {}", id, err),

@socksy socksy Jul 30, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not realllly sure we need this, but wanted to keep the diff here clean as a move

@konstantinoscs konstantinoscs Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This writes locally (similar to session persistence). Keep it

}
}

/// Writes a labelled notice to stderr, keeping stdout clean for command output.
pub(crate) fn notice_to_stderr(label: &str, msg: &str) {
fn notice_to_stderr(label: &str, msg: &str) {
let line = format!("{} {}\n", label.bold().yellow(), msg);
write_to_stderr(&line);
}
Expand Down
Loading