Add TypeScript contracts for custom statusline providers (#62034)

## What changed

Bundle a generated `statusline.d.ts` reference with the `create-statusline` skill, covering status snapshots, UI trees, colors, and canonical statusline item IDs. Add test-only `ts-rs` derives and an `UPDATE_STATUSLINE_TYPES` regeneration path.

Clarify that rate-limit usage percentages can exceed 100.

## Testing

Add a Rust test that checks key type exports in the installed skill and a strict TypeScript fixture covering provider rendering and invalid item IDs, row props, and colors.

GitOrigin-RevId: f615e0b3c2cd3d0d95a75de36ce0a84467ecd5b6
This commit is contained in:
Joe Savona
2026-11-17 11:58:26 +00:00
committed by copyberry
parent 59ac39addb
commit 7df454ceb5
17 changed files with 414 additions and 2 deletions
@@ -0,0 +1,82 @@
#![cfg(test)]
//! Generate the TypeScript reference and check the exports installed with the authoring skill.
use super::StatuslineState;
use crate::bottom_pane::StatusLineItem;
use crate::ui_tree::UiTree;
use codex_protocol::protocol::RateLimitWindow;
use codex_utils_absolute_path::AbsolutePathBuf;
use std::fmt::Write as _;
use std::path::Path;
use strum::IntoEnumIterator;
use ts_rs::TS;
#[test]
fn statusline_typescript_contract_matches_the_bundled_reference() -> color_eyre::Result<()> {
let output = tempfile::tempdir()?;
if let Some(destination) = std::env::var_os("UPDATE_STATUSLINE_TYPES") {
std::fs::write(destination, generate_reference(output.path())?)?;
return Ok(());
}
let home = AbsolutePathBuf::try_from(output.path().to_path_buf())?;
codex_skills::install_system_skills(&home)?;
let reference = codex_skills::system_cache_root_dir(&home)
.join("create-statusline/references/statusline.d.ts");
let reference = std::fs::read_to_string(reference.as_path())?;
for name in [
"StatuslineState",
"UiTree",
"RowElement",
"StatuslineItemId",
"Color",
] {
assert!(
reference.lines().any(|line| {
line.strip_prefix("export type ")
.and_then(|declaration| declaration.split_once('='))
.is_some_and(|(declared_name, _)| declared_name.trim_end() == name)
}),
"missing export {name} in statusline.d.ts"
);
}
Ok(())
}
fn generate_reference(output: &Path) -> color_eyre::Result<String> {
StatuslineState::export_all_to(output)?;
UiTree::export_all_to(output)?;
let mut generated = std::fs::read_to_string(output.join("statusline.d.ts"))?;
generated.push('\n');
// Item IDs use the same display serialization as the native field editor.
let items = StatusLineItem::iter()
.map(|item| serde_json::to_string(&item))
.collect::<Result<Vec<_>, _>>()?;
writeln!(
generated,
"export type StatuslineItemId = {};",
items.join(" | ")
)?;
for name in ["Text", "Bold", "Italic", "Underline", "Link", "Row"] {
let tag = name.to_ascii_lowercase();
writeln!(
generated,
"export type {name}Element = Extract<Element, {{ type: \"{tag}\" }}>;"
)?;
}
writeln!(generated, "export {}", RateLimitWindow::decl())?;
generated.push_str(
"export type ThemeColor = Extract<Color, \"primary\" | \"surface\" | \"accent\">;\n\
export type AnsiColor = Exclude<Color, ThemeColor | StatusColor | HexRgb>;\n",
);
let mut generated = generated
.lines()
.map(str::trim_end)
.collect::<Vec<_>>()
.join("\n");
generated.push('\n');
Ok(generated)
}
@@ -21,6 +21,7 @@ use serde::Serialize;
use strum_macros::Display;
#[derive(Serialize)]
#[cfg_attr(test, derive(ts_rs::TS), ts(export_to = "statusline.d.ts"))]
pub(crate) struct StatuslineState {
account: account::Account,
app: StatuslineStateApp,
@@ -29,20 +30,38 @@ pub(crate) struct StatuslineState {
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "App")
)]
struct StatuslineStateApp {
cli_version: &'static str,
display_mode: crate::history_cell::HistoryRenderMode,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Config")
)]
struct StatuslineStateConfig {
#[cfg_attr(test, ts(type = "StatuslineItemId[]"))]
statusline_items: Vec<StatusLineItem>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(optional))]
profile: Option<String>,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Thread")
)]
struct StatuslineStateThread {
#[cfg_attr(test, ts(inline))]
id: codex_protocol::ThreadId,
name: Option<String>,
agent: StatuslineStateAgent,
@@ -50,23 +69,41 @@ struct StatuslineStateThread {
workspace: StatuslineStateWorkspace,
usage: usage::Usage,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(optional))]
approval: Option<StatuslineStateApproval>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(optional))]
permissions: Option<StatuslineStatePermissions>,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Workspace")
)]
struct StatuslineStateWorkspace {
#[cfg_attr(test, ts(inline))]
cwd: codex_utils_path_uri::LegacyAppPathString,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Agent")
)]
struct StatuslineStateAgent {
state: StatuslineStateRunState,
}
#[derive(Serialize, Display)]
#[serde(rename_all = "lowercase")]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "RunState")
)]
pub(super) enum StatuslineStateRunState {
Starting,
Ready,
@@ -76,14 +113,21 @@ pub(super) enum StatuslineStateRunState {
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Model", optional_fields)
)]
struct StatuslineStateModel {
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(inline))]
access_program: Option<CyberAccessProgram>,
display_name: String,
#[serde(skip_serializing_if = "Option::is_none")]
id: Option<String>,
provider: String,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(inline))]
reasoning_level: Option<ReasoningEffort>,
#[serde(skip_serializing_if = "Option::is_none")]
service_tier: Option<String>,
@@ -92,6 +136,11 @@ struct StatuslineStateModel {
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Approval")
)]
struct StatuslineStateApproval {
policy: StatuslineStateApprovalPolicy,
reviewer: StatuslineStateApprovalReviewer,
@@ -99,6 +148,11 @@ struct StatuslineStateApproval {
#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "ApprovalPolicy")
)]
enum StatuslineStateApprovalPolicy {
Untrusted,
OnRequest,
@@ -108,15 +162,26 @@ enum StatuslineStateApprovalPolicy {
#[derive(Serialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "ApprovalReviewer")
)]
enum StatuslineStateApprovalReviewer {
User,
AutoReview,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Permissions")
)]
struct StatuslineStatePermissions {
display_name: String,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(optional))]
profile_id: Option<String>,
#[serde(flatten)]
enforcement: StatuslineStateEnforcement,
@@ -124,19 +189,31 @@ struct StatuslineStatePermissions {
#[derive(Serialize)]
#[serde(tag = "type", rename_all = "lowercase")]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "Enforcement")
)]
enum StatuslineStateEnforcement {
Managed {
file_system: StatuslineStateFileSystem,
#[cfg_attr(test, ts(inline))]
network: NetworkSandboxPolicy,
},
Disabled,
External {
#[cfg_attr(test, ts(inline))]
network: NetworkSandboxPolicy,
},
}
#[derive(Serialize)]
#[serde(tag = "type", rename_all = "lowercase")]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "FileSystem")
)]
enum StatuslineStateFileSystem {
Restricted,
Unrestricted,
@@ -265,3 +342,7 @@ impl ChatWidget {
})
}
}
#[cfg(test)]
#[path = "statusline_contract_tests.rs"]
mod contract_tests;
@@ -6,22 +6,36 @@ use codex_protocol::protocol::RateLimitWindow;
use serde::Serialize;
#[derive(Serialize)]
#[cfg_attr(test, derive(ts_rs::TS), ts(export_to = "statusline.d.ts"))]
pub(super) struct Account {
rate_limits: Vec<RateLimit>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(optional))]
workspace: Option<Workspace>,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "AccountWorkspace")
)]
struct Workspace {
headline: String,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "RateLimitSnapshot")
)]
struct RateLimit {
limit_id: &'static str,
limit_name: Option<String>,
#[cfg_attr(test, ts(type = "RateLimitWindow | null"))]
primary_limit: Option<RateLimitWindow>,
#[cfg_attr(test, ts(type = "RateLimitWindow | null"))]
secondary_limit: Option<RateLimitWindow>,
}
@@ -5,6 +5,11 @@ use crate::token_usage::TokenUsage;
use serde::Serialize;
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", optional_fields)
)]
pub(super) struct Usage {
context: Context,
#[serde(skip_serializing_if = "Option::is_none")]
@@ -14,6 +19,11 @@ pub(super) struct Usage {
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", optional_fields)
)]
struct Cost {
#[serde(skip_serializing_if = "Option::is_none")]
total_cost_usd: Option<f64>,
@@ -22,21 +32,39 @@ struct Cost {
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", optional_fields)
)]
struct Context {
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(as = "Option<f64>"))]
context_window_size: Option<i64>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(as = "Option<f64>"))]
used_tokens: Option<i64>,
#[serde(skip_serializing_if = "Option::is_none")]
#[cfg_attr(test, ts(as = "Option<f64>"))]
used_percentage: Option<i64>,
}
#[derive(Serialize)]
#[cfg_attr(
test,
derive(ts_rs::TS),
ts(export_to = "statusline.d.ts", rename = "TokenUsage")
)]
struct Counts {
#[cfg_attr(test, ts(type = "number"))]
total_input_tokens: i64,
#[cfg_attr(test, ts(type = "number"))]
cache_read_input_tokens: i64,
#[cfg_attr(test, ts(type = "number"))]
cache_write_input_tokens: i64,
#[cfg_attr(test, ts(type = "number"))]
other_input_tokens: i64,
#[cfg_attr(test, ts(type = "number"))]
output_tokens: i64,
}