diff --git a/packages/cli-rs/crates/tui/src/plugins/approve.rs b/packages/cli-rs/crates/tui/src/plugins/approve.rs index cb2c2659e9f..a1c7d4f47d5 100644 --- a/packages/cli-rs/crates/tui/src/plugins/approve.rs +++ b/packages/cli-rs/crates/tui/src/plugins/approve.rs @@ -1,17 +1,11 @@ -//! The host's question about a project plugin held back for approval (rich-plugins 3.9): a select row that toggles -//! such a plugin asks it, whichever plugin showed the row (the plugin manager's), since only the host decides what -//! runs (synthesis 3.6). +//! Ask before running a project plugin. Approval belongs to the displayed artifact, not its path alone. use opencode_plugin::loader::approval::{Artifact, Decision}; use opencode_ui::confirm::{ConfirmProps, confirm}; use crate::prelude::*; -/// Asks whether the build of the project plugin of `target` that the loader holds back now may run. The answer names -/// that build, so it records nothing when the build changed meanwhile (bigboi-1, carbon-1). Approve and Decline keep -/// the answer for this build; Escape, Ctrl+C, the header and the backdrop leave it pending (carbon-6). However the -/// question closes, `back` runs after it, once a library's answer is applied; a TypeScript plugin's tree may still be -/// hashed for its answer then. +/// Ask about the held build of `target`; record the answer only while it still identifies the same build. pub(super) fn ask(tui: &Tui, target: &str, back: impl Fn() + 'static) { let Some((held, unsaved)) = super::host::held(tui, target) else { return }; let artifact = match held { @@ -23,8 +17,7 @@ pub(super) fn ask(tui: &Tui, target: &str, back: impl Fn() + 'static) { Rc::new(move || { let Some(tui) = weak.upgrade() else { return }; let (target, artifact) = (target.clone(), artifact.clone()); - // After the confirm has closed, and before the list comes back; a TypeScript plugin's answer applies once its - // tree is hashed off the UI thread, and the list follows it then. + // Wait for the off-thread approval check before reopening the list. tui.app.defer(bind!(tui, |tui, _| { super::host::decide(&tui, &target, &artifact, decision, |tui, recorded| match recorded { Ok(true) => {} @@ -56,8 +49,7 @@ pub(super) fn ask(tui: &Tui, target: &str, back: impl Fn() + 'static) { tui.dialogs.replace(move |cx| confirm(cx, props.clone()), Some(closed), options); } -/// The question about `artifact`, found as plugin directory `target`: the library that would run, where it really is -/// when that is outside the directory, and its hash (bigboi-1, carbon-1). +/// Describe the actual library path, hash, and whether the decision can be saved. fn question(target: &str, artifact: &Artifact, unsaved: Option<&str>) -> String { let inside = artifact.script || std::fs::canonicalize(target).is_ok_and(|directory| artifact.path.starts_with(directory)); @@ -94,8 +86,6 @@ fn question(target: &str, artifact: &Artifact, unsaved: Option<&str>) -> String mod tests { use super::*; - // Expected (bigboi-1, bigboi-2, carbon-1): the question shows the library that would run and its hash, says when it - // lies outside the plugin directory, and says when the answer is not saved. #[test] fn the_question_names_the_library_and_says_what_is_not_saved() { let root = opencode_util::temp::tempdir().unwrap(); diff --git a/packages/cli-rs/crates/tui/src/plugins/btw.rs b/packages/cli-rs/crates/tui/src/plugins/btw.rs index 2a47ed5f6ff..62bd536f86a 100644 --- a/packages/cli-rs/crates/tui/src/plugins/btw.rs +++ b/packages/cli-rs/crates/tui/src/plugins/btw.rs @@ -1,8 +1,4 @@ -//! `/btw` (E.14, row F03, `feature-plugins/prompt/btw.tsx`): `session.aside` asks a one-shot side question with -//! the session's context through `session.generate`, without adding to the conversation, and shows the answer -//! in a large dialog. While answers are pending, a `/btw` spinner shows in `prompt.footer.status`. It is a plugin of -//! the one API (O-67): the spinner is a contract 2.0 surface (P6a), and the answer a dialog of the API both majors -//! share, whose body is a node of 1.x (2.0 has no keyed dialog). +//! `/btw` asks a side question with session context and shows the answer without interrupting the session. use opencode_api::client::Client; use opencode_api::generated::{SessionGenerateInput, SessionGenerateOutput}; diff --git a/packages/cli-rs/crates/tui/src/plugins/contain.rs b/packages/cli-rs/crates/tui/src/plugins/contain.rs index 9a1fc0a8112..e77fa8ac964 100644 --- a/packages/cli-rs/crates/tui/src/plugins/contain.rs +++ b/packages/cli-rs/crates/tui/src/plugins/contain.rs @@ -1,14 +1,4 @@ -//! The client's side of containment (synthesis 4.5, phase P4c). Under a parent, the client keeps its run record: the -//! parent made it, and handed over in it what the client before this one left. The client: -//! -//! - holds the build a crash named, by target and digest, in `plugin-crashes.json` in the state directory, and every -//! external plugin when the parent says safe mode, or when no parent guards it at all: their libraries are never -//! opened ([`opencode_plugin::Registry::admit`]); -//! - restores the session and the draft of the last snapshot, and shows one notice; -//! - publishes, on every path that changes them, the session on screen and the composer's exact text; -//! - on a real terminal, starts the watchdog; when a call it painted the notice for returns, says so on that line. -//! -//! The parent's half is the CLI's `contain`. +//! Report plugin calls to the supervising process and recover held builds after a crash. use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -163,7 +153,7 @@ fn notice(tui: &Rc, crash: &Crash, safe: bool, dropped: bool) { Some(artifact) => { let id = if artifact.id.is_empty() { artifact.target.clone().unwrap_or_default() } else { artifact.id.clone() }; - // The held build, not a loaded plugin of the same ID (review bigboi-3). + // Use the held build's identity, not a loaded plugin with the same ID. let held = opencode_plugin::Entry::held_key(artifact.target.as_deref().unwrap_or_default()); ToastOptions::new(Variant::Error, format!("It {}.{lost}", reason(call, crash.hang))) .title(format!("Plugin failed: {id}")) @@ -191,8 +181,7 @@ pub(crate) fn enable(tui: &Rc, key: &str) { } } -/// A call whose hang notice the watchdog painted over row 1 returned: the line says so, over the notice, and goes, so -/// the row shows what the UI drew there. +/// Replace a watchdog hang notice with a brief recovery notice when the call returns. fn responded(tui: &Rc, artifact: &Artifact, took: Duration) { let theme = tui.page(); let text = format!(" plugin {} responded after {:.1} s ", artifact.id, took.as_secs_f32()); @@ -236,8 +225,6 @@ pub fn sync(tui: &Tui) { mod tests { use super::*; - // Expected (review bigboi, inherited): a change of the crash list that cannot be written says so and leaves the - // file as it was, so a release that depends on it does not happen. #[test] fn a_crash_list_that_cannot_be_written_says_so() { use std::os::unix::fs::PermissionsExt; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs index 68721ca0d1e..7ebefd808d4 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/base_branch.rs @@ -1,6 +1,4 @@ -//! Base branch dialog (E.15b, row DLG46, `DiffBaseDialog` in `feature-plugins/system/diff-viewer.tsx`): the -//! location's local and remote branches, searched on the server as the user types (the host's query, after 150 ms). -//! The chosen branch is remembered per location and branch while the plugin is active. +//! Choose a local or remote comparison branch. use opencode_api::client::Client; use opencode_api::generated::{LocationQueryInput, VcsBranchListInput, VcsBranchListOutput}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs index 69acdbfff74..eac4e9c490a 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/file_menu.rs @@ -1,7 +1,4 @@ -//! Diff file menu (E.15b, row DLG49, `feature-plugins/system/diff-viewer-file-menu.tsx`): one row under a -//! right-clicked file heading or tree row that marks the file complete or incomplete. An overlay of the plugin's, -//! owned by the viewer's mount: it takes the focus, so the viewer's keys wait; Escape and a press outside close it, -//! and Enter or a click of the row runs it. +//! Context menu for a file heading or file-tree entry. use opencode_plugin::abi::interact::{Anchor, Bind, Button, Event, Handled, Interact, Layer, Overlay, PointerKind}; use opencode_plugin::abi::v2::{self, Node}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs index c7fbf2788e6..9779eff0e54 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/help.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/system/diff-viewer.tsx`. +//! Diff viewer keyboard help. use opencode_plugin::abi::{Dialog, Host, Layout, Node, Panel, PanelSize, Read, Span, Width}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs index 3b44523e32a..7f9839a2127 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/keys.rs @@ -1,10 +1,4 @@ -//! The `diff.*` bindings (E.15a): the viewer's commands (`diff-viewer.tsx:588-781`) and the global `diff.open` -//! (`:1311-1361`). Of the 26 `diff.*` keybinds in `config/keybind.ts`, 20 are viewer commands, `diff.open` opens it, -//! and the five deprecated tree keys (`diff.toggle`, `.expand`, `.expand_all`, `.collapse`, `.switch_focus`) are -//! kept for config only and register nothing, as in TS. -//! -//! The viewer's keys are a layer of its surface (P6c): each bind is the user's keybind of the command's name -//! ([`Bind::command`]), heard by the surface's handler while the panel has the focus or the route shows. +//! Diff commands and key bindings for route and docked views. use opencode_plugin::abi::interact::{Bind, Layer, LayerScope}; @@ -32,9 +26,7 @@ pub enum Action { Help, } -/// The viewer's commands in TS order. `app.exit` closes the viewer while it has the input; the specific bindings -/// win over its `ctrl+d`. Its `ctrl+c` is the host's: no plugin layer takes the reserved chord (P2), and the host -/// closes the plugin's menu, panel or route that has the input on it, as `app.exit` closes the viewer in TS. +/// Viewer-specific bindings take precedence over exit while the viewer owns input. pub const COMMANDS: [(&str, &str, Action); 21] = [ ("diff.close", "Close diff viewer", Action::Close), ("diff.down", "Move diff viewer down", Action::Down), diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs index 6e7c76e0a74..f91c2ca1ef9 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/mod.rs @@ -1,13 +1,4 @@ -//! The diff viewer (E.15a and E.15b, row F15, `feature-plugins/system/diff-viewer.tsx`): the built-in -//! `opencode.diffs`, a plugin of contract 2.0 on both carriers (P6c, synthesis 4.9). `/diff` docks the viewer beside -//! the session as its panel, or opens it as a full-screen route outside a session. The viewer loads the VCS or -//! last-turn diff, and shows each file as a card under a sticky header, with the file tree beside the cards when the -//! screen is wide enough, split or unified hunks by width, and reviewed marks. -//! -//! What the host did for the old viewer it does for any plugin: the cards are a windowed list, the hunk cursor is a -//! step, the reading position a keep, the top edge's color a paint of `layout`, and the panel, the keys, the menu and -//! the dialogs are surfaces, a layer, an overlay and host dialogs. One viewer shows at a time: its state lives from -//! its mount's begin to its end. +//! The built-in diff viewer, shown as a route or a docked panel. use opencode_api::generated::{SessionExecutionInterruptedDataReason, V2Event}; use opencode_plugin::abi::interact::{Button, Event, Handled, OpenPanel, PointerKind}; @@ -111,7 +102,7 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { ]; for (name, run) in commands { let ran = diffs.clone(); - // A pick closes its keyed dialog, also once no viewer is left to take it (review carbon-4). + // A pick must close its dialog even if the viewer is gone. let closes = match name { PICK_SOURCE => Some(sources::KEY), PICK_BASE => Some(base_branch::KEY), diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs index 4c1f7db2385..0544c8e345a 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/sources.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/system/diff-viewer.tsx`. +//! Select the diff source for a location. use opencode_plugin::abi::{Action, Dialog, Host, Select, SelectOption}; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs index 1a31be5877b..b24260fc725 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/tree.rs @@ -1,4 +1,4 @@ -//! TypeScript: `diff-viewer-file-tree-utils.ts`, `diff-viewer-file-tree.tsx`. +//! Display and navigate the diff viewer's file tree. use std::collections::BTreeSet; diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs index 194345fa555..426b8910773 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/view.rs @@ -1,7 +1,4 @@ -//! The viewer's tree: the header, the cards, the footer and the file tree, from the viewer's state. The cards are a -//! windowed list (P3): only those near the view have widgets, and a card that did not change is kept whole -//! ([`v2::View::memo`]). A card's header sticks to the top of its card, its hunks are anchors a step walks, and the -//! fixed edge above the list takes the color of the card at the top from `layout`. +//! Diff cards form a virtual list: build only cards near the viewport and retain their state across revisions. use std::rc::Rc; @@ -474,9 +471,7 @@ fn tree_pane(viewer: &Viewer, cx: &mut v2::View<'_>) -> Node { ) } -/// The fixed top edge takes the reviewed color of the card at the top, in the frame that shows it. The edge is there -/// only with the cards, so a frame without their scroll (loading, a message) paints nothing, and logs no paint of a -/// missing box (PL-10). +/// Paint the fixed edge from the top card only when the cards are visible. pub fn layout(geometry: &Geometry) -> LayoutReply { if geometry.scroll(FILES).is_none() { return LayoutReply::default(); @@ -489,7 +484,6 @@ pub fn layout(geometry: &Geometry) -> LayoutReply { mod tests { use super::*; - // Expected (PL-10): the edge is painted only in a frame that has the cards' scroll. #[test] fn the_edge_is_painted_only_with_the_cards() { assert!(layout(&Geometry::default()).paints.is_empty()); diff --git a/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs b/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs index 1e88686a4e6..17d0dd1dc0d 100644 --- a/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/diffs/viewer.rs @@ -118,8 +118,7 @@ pub enum Load { Ready { base: Option, files: Vec }, } -/// The plugin's memory, kept while it is active (`storage.memory("review")`): the last source and the chosen base per -/// location and branch. +/// Remember the selected source and comparison base per location and branch. #[derive(Default)] pub struct Memory { pub source: Option, @@ -144,7 +143,7 @@ pub enum Showing { pub enum Preview { Loading, Failed, - /// Bytes that the host's image decoder refuses (TS `onError`): no size and no preview to click. + /// The host cannot decode these bytes. Omit the size and preview action. Undecodable, /// The bytes, and the width and height the host decodes them to. Ready(std::rc::Rc<[u8]>, (u32, u32)), @@ -189,8 +188,7 @@ pub struct Viewer { /// Image previews by file, read once per file list. pub previews: HashMap, pub menu: Option, - /// The tree's selected row and its rows when they last scrolled it: the selection scrolls into view only when - /// they change, as TS's effect does. + /// Scroll to the selected row only when the selection or its rows change. pub tree_mark: (Option, usize), pub contents: Contents, /// The last view shows this state: a wake that changed nothing of it keeps the tree. @@ -216,7 +214,7 @@ pub struct Shown { } impl Viewer { - /// What its view shows of it now (each event changes a set by one, so the sizes tell). + /// State exposed to the current view. pub fn shown(&self) -> Shown { Shown { selected: self.selected, @@ -309,8 +307,8 @@ impl Viewer { self.docked() || self.width < FULL_LAYOUT_MIN_WIDTH } - /// Whether the viewer has the input: always full screen, else while its panel has the focus. A dialog takes the - /// focus without changing the panel's (TS `panel.focused`). + /// A fullscreen viewer owns input; a docked viewer must hold panel focus. Opening a dialog does not transfer + /// ownership of the panel. pub fn focused(&self) -> bool { !self.docked() || self.panel.is_some_and(|panel| panel.focused) } @@ -642,11 +640,7 @@ impl Viewer { self.forget(host); } - /// What a turn event says to the viewer: in `turn` mode the viewer of that session loads again when one of its - /// turns ends (TS's `createEffect` on `session.status`, running to idle), and says whether it did. It hears the - /// end itself: the status read when the UI hears of an event may already be idle again, for a turn that started - /// and ended before then (`steps/flakes-8.md`). A turn it saw start whose end the connection may have lost (a - /// reconnect, or signals the UI skipped) loads it again too (carbon's review of P6c, 6). + /// Refresh a session's turn diff when its turn ends. pub fn turn(&mut self, host: &dyn Host, diffs: &Diffs, turn: Turn<'_>) -> bool { let mine = |session: &str| self.mode == Mode::Turn && self.session() == Some(session); let ended = match turn { diff --git a/packages/cli-rs/crates/tui/src/plugins/fallback.rs b/packages/cli-rs/crates/tui/src/plugins/fallback.rs index caf1a26a44d..c411257b573 100644 --- a/packages/cli-rs/crates/tui/src/plugins/fallback.rs +++ b/packages/cli-rs/crates/tui/src/plugins/fallback.rs @@ -1,7 +1,4 @@ -//! The host's own `/plugins` while the plugin manager (`opencode.plugins`) has failed (synthesis 3.6, 4.10): the toasts -//! and the home footer still say "Run /plugins", so the host lists the TUI plugins and their errors, read only. Enter -//! on a row with an error shows it; the user's enter or click on the manager's own row enables it again, which brings -//! the manager back. Rows name registry entries by key, so a held build of the manager's ID is not the manager. +//! Host fallback for `/plugins` when the plugin manager fails. use opencode_plugin::{Entry, Source, Status}; @@ -67,7 +64,7 @@ fn show(tui: &Rc, focus: Option) { })); props.actions = vec![view_error]; props.on_select = Some(Rc::new(bind!(weak, |tui, option: &SelectOption| { - // A key or a click, not a run of the submit by name, as a plugin's `dispatch` runs it (review bigboi-1). + // Require a user key or click before toggling a plugin. let by_input = picked .upgrade() .is_some_and(|handle| handle.borrow().as_ref().is_some_and(|handle| handle.by_input())); diff --git a/packages/cli-rs/crates/tui/src/plugins/fetch.rs b/packages/cli-rs/crates/tui/src/plugins/fetch.rs index 80db84fffa5..fea6b420bf5 100644 --- a/packages/cli-rs/crates/tui/src/plugins/fetch.rs +++ b/packages/cli-rs/crates/tui/src/plugins/fetch.rs @@ -1,5 +1,4 @@ -//! The plugins' one route for I/O (O-67): a built-in builds its request with a generated `*_call` builder and turns it -//! into an [`abi::Fetch`] here; the host sends a fetch through its own client, on the transport the TUI runs on now. +//! Route built-in plugin requests through the same fetch interface as external plugins. use opencode_api::client::{Body, Call}; use opencode_plugin::abi; diff --git a/packages/cli-rs/crates/tui/src/plugins/goal.rs b/packages/cli-rs/crates/tui/src/plugins/goal.rs index ef3a5dbe464..d8ba85521cd 100644 --- a/packages/cli-rs/crates/tui/src/plugins/goal.rs +++ b/packages/cli-rs/crates/tui/src/plugins/goal.rs @@ -1,11 +1,4 @@ -//! The goal `/goal` set on a session (E.14, rows F02 and DLG45, `feature-plugins/prompt/goal.tsx`): the goal plugin's -//! RPC read, the status under the prompt, and the goal panel, for the prompt footer plugin. The panel is a dialog of -//! the API both majors share, whose body is a node of 1.x: contract 2.0 has no keyed dialog (P6a). -//! -//! [`Goals`] keeps the goal of each session a mounted footer shows. The first footer of a session reads its goal, and -//! every tracked session is read again after a reconnect, since changes published meanwhile were missed; the `changed` -//! events keep them current. A change that arrives while a read is in flight is newer than its reply, so each read and -//! change takes a turn, and a reply of an older turn is dropped. +//! Session goal status, commands, and progress panel. use opencode_api::client::Client; use opencode_api::generated::{LocationQueryInput, RpcCallInput, RpcCallOutput, SessionCommandInput, V2Event}; @@ -44,7 +37,7 @@ pub enum Status { Complete, } -/// The goals of the sessions the mounted footers show (TS `createGoal`, once per session). +/// Track goals for sessions with a mounted goal footer. #[derive(Default)] pub struct Goals { sessions: RefCell>, diff --git a/packages/cli-rs/crates/tui/src/plugins/home_footer.rs b/packages/cli-rs/crates/tui/src/plugins/home_footer.rs index 3f536fd4d27..e5bbb0dcb56 100644 --- a/packages/cli-rs/crates/tui/src/plugins/home_footer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/home_footer.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/home/footer.tsx`. +//! Built-in home footer. use opencode_plugin::abi::v2::{Node, Place, Surface}; use opencode_plugin::abi::{self, Click, Layout, Placement, Span, Width}; diff --git a/packages/cli-rs/crates/tui/src/plugins/host.rs b/packages/cli-rs/crates/tui/src/plugins/host.rs index 9c1d5d1ce8e..00914b55f79 100644 --- a/packages/cli-rs/crates/tui/src/plugins/host.rs +++ b/packages/cli-rs/crates/tui/src/plugins/host.rs @@ -33,14 +33,13 @@ pub struct Plugins { pub(crate) published: RefCell>, #[cfg(feature = "ts")] pub scripts: RefCell>>, - /// The plugins as the plugins that read them last heard of them (P6b), and whether a tell is queued. + /// Last plugin list delivered to subscribers. told: RefCell>, telling: Cell, /// The host's own `/plugins` while the plugin manager has failed. fallback: RefCell>, server_parts: RefCell>, - /// The plugins not loaded the user was told of this run, and whether the server's plugins were heard yet: the one - /// notice waits for them, so it names their TUI parts too. + /// Wait for both local and server plugins before reporting skipped entries once per run. told_skipped: RefCell>, heard_server: Cell, } @@ -108,8 +107,7 @@ impl Host for Tui { Some(serde_json::Value::Object(object)) => object.into_iter().chain(fields.clone()).collect(), _ => fields.clone(), }; - // The plugin's bound holds for the value the merge makes under the lock, which another client's writes may have - // grown since this client read it (re-review final pass, the storage bound). + // Check the merged size under the storage lock; another client can enlarge the value. queue(self, key, Some(serde_json::Value::Object(shown).to_string()), move |storage, key| { let merge = move |stored: &mut Value| match stored.as_object_mut() { Some(object) => object.extend(fields), @@ -141,8 +139,7 @@ impl Host for Tui { }; let mut options = ToastOptions::new(variant, toast.message.clone()); options.title = toast.title.clone(); - // A toast about a session offers to open it, unless the session's family is on screen. - // A plugin's toast waits behind the host's own notice of a plugin (PL-2). + // Only offer to open a session outside the visible family. Queue plugin toasts behind host failure notices. let Some(session) = toast.session.as_ref().map(|id| SessionID(id.clone())) else { return self.toasts.show_behind_kept(options); }; @@ -161,15 +158,14 @@ impl Host for Tui { } fn failed(&self, id: &str) { - // After what the failing call asked for, as in TS, where its toast showed before the error was thrown: a toast - // replaces the one on screen, so the report must come last. + // Show the failure report after the failing call's effects so an earlier toast cannot hide it. let title = format!("Plugin failed: {id}"); self.app.defer(bind!(self, |tui, _| failed_toast(&tui, title.clone(), String::new()))); self.reads.changed(self); } fn slow(&self, id: &str, cost: &str) { - // A frame that made it slow may close after the plugin failed or was turned off: then it has its own report. + // A failed or disabled plugin already has its own report. if !self.plugins.entries().iter().any(|entry| entry.id == id && entry.status == Status::Active) { return; } @@ -177,7 +173,7 @@ impl Host for Tui { .title(format!("Plugin is slow: {id}")) .keep(); tell_plugins(self); - // Disabling the manager would leave no `/plugins` (review carbon-3). + // Keep the manager available to reopen `/plugins`. if id == super::manager::ID { return self.toasts.show(options); } @@ -204,9 +200,7 @@ impl Host for Tui { // A dialog surface on screen mounts again from the registration that replaced the one that ended. let reloaded = id.to_owned(); self.app.defer(bind!(self, |tui, _| super::panel::remount(&tui, &reloaded))); - // A reload of the plugin's registrations replaced the one that ended, which has the panel too: the panel stays - // open and mounts again from the new one, as TS takes a registration without closing it (CT-29). A plugin that - // failed or ended loses it. + // Keep the panel open across registration reloads and remount its new surface. let kept = self.panels.current().is_some_and(|target| { target.plugin == id && self.plugins.has_panel(id, &target.name) @@ -366,7 +360,7 @@ impl Host for Tui { return false; } let root = |session: &str| self.data.read(|state| state.root(&SessionID(session.to_owned()))).0; - // The tabs as the call's earlier edits left them (TS `ui.tabs` acts on each in order). + // Apply tab edits in call order. let (mut open, mut current) = (self.tabs.open_ids(self), self.tabs.current(self)); for edit in staged { match edit { @@ -391,7 +385,7 @@ impl Host for Tui { } match edit { abi::TabEdit::Open { .. } | abi::TabEdit::Focus { .. } => true, - // `move` takes any session of a tab's family; `close` only the tab's own ID, as in TS. + // Move accepts any session in a tab family; close requires the tab's own ID. abi::TabEdit::Move { session, .. } => open.contains(&root(session)), abi::TabEdit::Close { session } => session.clone().or(current).is_some_and(|id| open.contains(&id)), } @@ -590,9 +584,7 @@ impl Host for Tui { } } -/// Counts each change of the host's own state (its local state and settings) in [`Host::local_revision`], once and -/// before the watchers hear it, so every view after it hears it as `local` once (review carbon-6). Called before any -/// claim mounts: listeners run in the order they subscribed. +/// Advance the shared local revision before notifying watchers, once per change. pub(crate) fn count_local(tui: &Tui) { let revision = tui.reads.revision.clone(); let local = tui.local.subscribe(move || revision.set(revision.get() + 1)); @@ -649,7 +641,7 @@ fn queue( pending.fetch_add(1, Ordering::SeqCst); let (key, proxy) = (key.to_owned(), tui.app.proxy()); let writer = tui.reads.writer.get_or_init(|| { - // A write refused under the lock leaves the disk as it was: what this client showed for it goes. + // A refused write leaves the disk unchanged; invalidate its optimistic value. let weak = tui.weak(); tui.app.on_message(move |_, _: &Refused| { if let Some(tui) = weak.upgrade() { @@ -679,7 +671,7 @@ fn queue( } } -/// Posted when a plugin storage write was refused under the lock. +/// Notification of a storage write refused under the lock. struct Refused; /// Waits until every plugin storage write queued so far is on disk. @@ -738,14 +730,11 @@ pub struct Reads { key: Cell, /// The JSON text of each storage key read or written, so a write shows at once and storage works without disk. stored: RefCell>>, - /// The one worker that writes the plugins' storage, so writes land in the order they were made. + /// Serialize plugin storage writes. writer: OnceCell, /// The writes queued and not yet on disk. pending: Arc, - /// A write was refused under the lock since the keys were last read from disk: what `stored` shows for it is no - /// file's. It stays set until a reload from disk with no write pending, so neither a correction that could not be - /// posted nor one skipped while another write was queued leaves the cache apart from the files (re-review last - /// pass). + /// Reload disk state after a refused write before trusting the cache. dirty: Arc, /// The mounted claims' pushes, which a storage write calls with `local` from the effect queue. watchers: RefCell>>, @@ -760,8 +749,7 @@ pub struct Reads { pub(super) surface: RefCell>>, /// The plugin and activation whose dialog is on screen, until it closes. pub(super) owner: RefCell>, - /// The showing `owner` was recorded for, by number, and the last number given: a close clears the owner of its own - /// showing only, whichever activation updated it since (big-boi ds-1). + /// A close clears only its own showing, even when a new activation owns the next one. pub(super) showing: Cell, pub(super) showings: Cell, /// The action the next plugin dialog runs as it closes (`abi::Dialog::Dismissable`), until that dialog takes it. @@ -1096,7 +1084,7 @@ fn set_setting(tui: &Tui, name: &str, value: Value) { }); } -/// A registry entry as a plugin reads it: without the error, which may hold another plugin's secrets (review bigboi-2). +/// Omit error text from plugin-visible entries: it may contain another plugin's secrets. fn entry(entry: opencode_plugin::Entry) -> abi::PluginEntry { let status = match entry.status { Status::Active => abi::PluginStatus::Active, @@ -1140,7 +1128,7 @@ pub fn tell_plugins(tui: &Tui) { if *tui.plugins.told.borrow() == entries { return; } - // The manager that serves `/plugins`, not a held build of its ID (review bigboi-3). + // Identify the active manager, not a held build sharing its ID. let manager = opencode_plugin::Entry::plugin_key(super::manager::ID); let failed = |entries: &[opencode_plugin::Entry]| { entries.iter().any(|entry| entry.key == manager && matches!(entry.status, Status::Failed(_))) @@ -1159,9 +1147,7 @@ pub fn tell_plugins(tui: &Tui) { pub(super) const APPROVAL: &str = "host.approval"; pub(super) const FALLBACK: &str = "host.plugins"; -/// Whether the host's approval question or its own `/plugins` is on screen: then no plugin's dialog, route or -/// navigation replaces or clears it, which would dismiss the question, or show a lookalike of it, or take the way to -/// recover from the user (review carbon-9). What plugin `id` asked for, `what`, is dropped. +/// Block plugin navigation and dialogs while the host approval question or fallback manager is visible. fn guarded(tui: &Tui, id: &str, what: &str) -> bool { let guarded = matches!(tui.dialogs.key().as_deref(), Some(APPROVAL | FALLBACK)); if guarded { @@ -1187,8 +1173,7 @@ fn status(status: opencode_store::SessionStatus) -> abi::SessionStatus { } } -/// The built-ins in TS order (`plugin/builtins.ts`), with the ones from other crates ([`crate::Deps::builtins`], -/// Mermaid and LaTeX) in their TS place after `stats`, and the diff viewer last. The storybook (F14) is excepted (Q17). +/// Register built-ins in palette order, including the renderers supplied through [`crate::Deps::builtins`]. fn builtins(external: Vec, abi: bool) -> Vec { // On the other carrier each plugin's calls cross the C ABI's byte shims ([`Builtin::Abi`]). let carried = |builtin: Builtin| match builtin { @@ -1250,8 +1235,7 @@ pub fn install(tui: &Rc) { super::contain::install(tui); tui.plugins.activate(&host(tui)); tell_plugins(tui); - // The plugins read the keymap (`keymap.pending()`, `keymap.active()`, `keymap.commands()`): the pending keys, and - // the layers and focus that decide what a key reaches, as TS's keymap selectors follow its state. + // Notify plugin keymap readers when pending keys, layers, or focus change. let keymap = tui.keymap.keymap().on_state(bind!(tui, |tui| local_changed(&tui))); tui.layers.borrow_mut().push(keymap); crate::features::events::subscribe(tui, ["plugin.updated", "server.connected"], |tui, event| { @@ -1312,13 +1296,8 @@ fn sync_server_plugins(tui: &Tui) { ); } -/// The TUI parts of the active server plugins, which TS loads from the server's list (`serverTuiPlugins`, -/// `context.tsx:96-103`, `301-305`): with the JS host the loader loads them, from the local path or the package -/// cache the server reports, holding for approval those the user's own configuration does not name (O-162); without -/// it they are listed as not loaded, unless their target is listed already, and a part the server no longer lists -/// leaves the list. A local path from a server on another machine names nothing here, and is left out. +/// Reconcile TUI entries supplied by the active server plugins. fn set_server_parts(tui: &Rc, plugins: &[PluginInfo]) { - // Only the client that loads external plugins has TS's reconcile to stand in for. let Some(loader) = tui.plugins.loader.borrow().clone() else { return }; let here = same_machine(tui.startup.args.local, tui.data.client().base_url()); let typed: Vec = plugins @@ -1368,8 +1347,7 @@ fn set_server_parts(tui: &Rc, plugins: &[PluginInfo]) { } } -/// Tells the user once a run, in the host's notice lane, which TypeScript plugins are not loaded and why: the ones not -/// told yet, grouped by reason, once the server's plugins were heard (FT-10). +/// Report each skipped TypeScript plugin once per run, grouped by reason. fn tell_skipped(tui: &Tui) { if !tui.plugins.heard_server.get() || tui.plugins.loader.borrow().is_none() { return; @@ -1411,9 +1389,7 @@ fn tell_skipped(tui: &Tui) { tui.toasts.show(options); } -/// Whether the server runs on this machine, so the paths it reports are this machine's: one the client started or the -/// service (no `--server`), or a `--server` on a loopback address. A loopback port may still be a tunnel to another -/// machine; a path it reports then needs approval like any the user's configuration does not name (O-162). +/// Trust server filesystem paths only for a local server. fn same_machine(local: bool, url: &url::Url) -> bool { local || match url.host() { @@ -1424,10 +1400,7 @@ fn same_machine(local: bool, url: &url::Url) -> bool { } } -/// The `plugins` entries of the user's own configuration as written, in the order TS applies them, removals (`-…`) -/// included (carbon recheck-1): the global opencode config's (TS `ConfigDiscovery`: `opencode.json`, then -/// `opencode.jsonc`, in the global config directory), then `cli.json`'s. Each is a package's spec, a path or a -/// selector; a file that does not parse names none. +/// Apply global config entries and removals in configuration order. fn user_plugins(tui: &Tui, config_dir: &Path) -> Vec { let global = ["opencode.json", "opencode.jsonc"] .iter() @@ -1479,8 +1452,7 @@ fn pending_toast(tui: &Tui, target: &str, message: &str) { pub struct External { pub config_dir: PathBuf, pub cwd: PathBuf, - /// Targets loaded beside the configured ones, which a config change keeps and settings never save: `plugin dev`'s - /// library (review bigboi-9). + /// Extra plugin targets that survive config reloads without being persisted, including `plugin dev`. pub dev: Vec, } @@ -1494,7 +1466,7 @@ pub type JsHost = opencode_plugin::pipe::Config; #[cfg(not(feature = "ts"))] pub enum JsHost {} -/// Whether a JS host runs the TypeScript plugins: never in a build without the `ts` feature. +/// Whether this client can run JavaScript plugins. fn js_host(tui: &Tui) -> bool { #[cfg(feature = "ts")] return tui.plugins.scripts.borrow().is_some(); @@ -1525,8 +1497,7 @@ pub fn external(tui: &Rc, external: External) { external_with(tui, external, scripts); } -/// [`external`], with the TypeScript plugins on a JS host that runs as `scripts` says (P7); without one they are listed -/// as skipped. +/// Load external plugins using the given JS host configuration. Without a host, list TypeScript plugins as skipped. pub fn external_with(tui: &Rc, external: External, scripts: Option) { let builds: Vec = external.dev.iter().map(|library| Build::new(Path::new(library).with_file_name("build.log"))).collect(); @@ -1541,7 +1512,6 @@ pub fn external_with(tui: &Rc, external: External, scripts: Option) let entries = configured(tui, tui.plugins.skipped()); let project = opencode_plugin::loader::project_root(&external.cwd); let loader = Loader::new(Rc::new(Native), external.config_dir, external.cwd, entries); - // Luau plugins (O-178): on in a build with them, unless `OPENCODE_PLUGIN_LUAU=0` turns them off. #[cfg(luau)] let loader = match opencode_plugin::luau::enabled() { true => { @@ -1612,7 +1582,7 @@ pub fn external_with(tui: &Rc, external: External, scripts: Option) tell_plugins(&tui); tell_skipped(&tui); })); - // The server's plugins may have been heard before there was a loader. + // Server entries can arrive before the loader starts. let server = tui.reads.server.borrow().1.clone(); set_server_parts(tui, &server); tell_skipped(tui); @@ -1622,12 +1592,10 @@ pub fn external_with(tui: &Rc, external: External, scripts: Option) /// author saves in an editor and looks back at the TUI later, past the 5 s of a toast's default (dx-fresh). const FAILED_BUILD: Duration = Duration::from_secs(24 * 60 * 60); -/// `plugin dev`'s `build.log` beside its library, which its builds in the background publish in the watched directory: -/// empty after a build that passed, the compiler's output after one that failed. A failed build keeps the running -/// version and said so only in the log file (PL-7). +/// Watch the development build log; an empty log means success. struct Build { log: PathBuf, - /// When the log was written last, and whether a build had failed then. + /// Last log timestamp and failure state. seen: Cell<(Option, bool)>, } @@ -1642,7 +1610,7 @@ impl Build { (meta.as_ref().and_then(|meta| meta.modified().ok()), meta.is_some_and(|meta| meta.len() > 0)) } - /// Tells a build since the last look: one that failed names its log, and the first to pass after it says so. + /// Report build failure and the first subsequent recovery. fn tell(&self, tui: &Tui) { let now = Self::read(&self.log); let (written, failed) = self.seen.replace(now); @@ -1672,7 +1640,7 @@ pub fn held(tui: &Tui, target: &str) -> Option<(Result, Option Some((loader.held(target)?, loader.unsaved())) } -/// Reconciles the external plugins with their directories now, as the watcher does after a change. +/// Reconcile external plugins against the current contents of their directories. pub fn reconcile(tui: &Rc) { let loader = tui.plugins.loader.borrow().clone(); if let Some(loader) = loader { @@ -1680,12 +1648,7 @@ pub fn reconcile(tui: &Rc) { } } -/// Records the user's `decision` on `artifact`, the build of `target` they were shown, once the build on the disk is -/// identified again, and applies it: an approved build loads at once. `done` gets `Ok(false)` when nothing was recorded -/// as the build changed since (bigboi-1), and an error when the decision cannot be saved (bigboi-7). A TypeScript -/// plugin's tree is hashed off the UI thread (FT-2), so `done` runs in a later turn; a library's, at once. An answer -/// the user gave again on `target` before the hash ended supersedes this one: it records nothing, and `done` does not -/// run (review jsnpm-5). +/// Recheck the on-disk artifact before applying the user's decision about a build. pub fn decide( tui: &Rc, target: &str, diff --git a/packages/cli-rs/crates/tui/src/plugins/keep.rs b/packages/cli-rs/crates/tui/src/plugins/keep.rs index 3a9e12eb02b..58271a9d176 100644 --- a/packages/cli-rs/crates/tui/src/plugins/keep.rs +++ b/packages/cli-rs/crates/tui/src/plugins/keep.rs @@ -1,5 +1,4 @@ -//! What a built-in's slot surface (contract 2.0, P6a) answers for 1.x's `Render::Keep` and `Render::Hide`. Its own file, -//! so a built-in's source builds as a library too (`crates/plugin/examples/home-footer`). +//! Shared retained and hidden nodes for built-in slot surfaces. use opencode_plugin::abi::v2::Node; diff --git a/packages/cli-rs/crates/tui/src/plugins/manager.rs b/packages/cli-rs/crates/tui/src/plugins/manager.rs index 22d92c3ac45..82cfece80ee 100644 --- a/packages/cli-rs/crates/tui/src/plugins/manager.rs +++ b/packages/cli-rs/crates/tui/src/plugins/manager.rs @@ -1,14 +1,4 @@ -//! The plugin manager (E.18b, `feature-plugins/system/plugins.tsx`): the built-in `opencode.plugins` with `plugins.list` -//! (`/plugins`), a plugin of the one API (P6b, synthesis 4.10) on both carriers. It reads the TUI plugins -//! ([`abi::Read::plugins`]) and hears when they change ([`abi::Setup::on_plugins`]); it never changes them. A row that -//! enables or disables a plugin, or asks to approve a project's plugin, is a toggle row, which only the host runs, on the -//! user's key or click (synthesis 3.6). The server rows come from `GET /api/plugin` of the location the manager opened -//! at; check and update are server calls too. -//! -//! Built-ins are internal and hidden until `ctrl+a`; a configured TypeScript plugin is listed as `skipped` with the -//! reason as its error (F16), and an external plugin that failed as `failed` with its error. Enter on a row that is not a -//! toggle opens its error, if any. A project plugin held back for approval (rich-plugins 3.9, not in TS) is listed -//! `pending` or `declined`. +//! Built-in manager for local and server plugins. use opencode_api::client::Client; use opencode_api::generated::{ @@ -37,8 +27,7 @@ pub fn plugin() -> abi::Plugin { struct State { opened: Cell, erring: Cell, - /// The server-list reads and checks asked for so far: only the reply to the newest one is shown, whatever order - /// they come back in (TS's resource keeps the newest). + /// Accept only the newest server list or check response. asked: Cell, directory: RefCell, server: RefCell>>, @@ -71,8 +60,7 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { host.dialog(Dialog::Select(list(host, state, None))); state.fetch(host, Asked::List(state.opened.get(), state.next())); }); - // The list's own commands act only while it shows: run by name with no list, they open nothing (review carbon-5). - // The internal rows' switch needs no guard: an open starts it again, and only an open list shows it. + // Ignore manager actions when the list is closed. let internal = state.clone(); setup.command(hidden("opencode.plugins.internal"), move |host, _| { internal.internal.set(!internal.internal.get()); @@ -110,8 +98,7 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { host.dialog(Dialog::Select(list(host, &back, key.map(str::to_owned)))); } }); - // After the host's question about a held build: the list on the row as it is now, and the server list read again, - // as `plugin.updated` went unheard while the question showed (review carbon-2). + // Refresh server entries after approval because list subscriptions stop while the question is open. let asked = state.clone(); setup.command(hidden("opencode.plugins.asked"), move |host, key| { if asked.opened.get() > 0 && !host.dialog_open(LIST) { @@ -211,7 +198,7 @@ impl State { } fn rows(&self, read: &dyn Read) -> Vec { - // Not the manager that runs, whose activation this is; a held build of its ID is a row (review carbon-3). + // A held build sharing the manager's ID is a separate row. let running = |entry: &PluginEntry| entry.id == ID && entry.active; let mut local: Vec = read.plugins().into_iter().filter(|entry| !running(entry)).map(Row::Tui).collect(); // A package without a server part runs nothing there; its TUI part has its own row. @@ -249,8 +236,7 @@ fn list(read: &dyn Read, state: &State, focus: Option) -> Select { }; let checking = state.checking.get(); let error = command("opencode.plugins.error", None); - // TS's order: check, then on the row view error (its own key), the host's toggle, update, and view error on enter; - // the toggle is the host's, which comes after these, and never shares a row with update or with the last. + // Keep the host's toggle distinct from plugin-supplied update and error actions. let mut actions = vec![SelectAction { title: if checking { "checking for updates" } else { "check for updates" }.to_owned(), key: Some("ctrl+r".to_owned()), @@ -260,7 +246,7 @@ fn list(read: &dyn Read, state: &State, focus: Option) -> Select { rowless: true, command: Some("dialog.plugins.check".to_owned()), disabled: checking, - // Kept with no package, so the server list's reply changes the select in place (review carbon-5). + // Keep the select mounted while waiting for the server's package list. hidden_all: !rows.iter().any(|row| row.package().is_some()), }]; actions.extend([ @@ -395,7 +381,7 @@ impl Row { } } - /// The project plugin's build waits for the user's approval, or was declined. + /// Whether the user still needs to approve this build or has declined it. fn held(&self) -> bool { matches!(self, Row::Tui(entry) if matches!(entry.status, PluginStatus::Pending | PluginStatus::Declined)) } @@ -444,7 +430,7 @@ impl Row { fn local(&self) -> bool { match self { Row::Server { plugin, .. } => matches!(plugin.source, PluginSource::Local(_)), - // TS's `path.isAbsolute`, which on Windows takes a rooted path without a drive (`/plugins/x`) too. + // On Windows a drive-less rooted path is absolute for the plugin manager. Row::Tui(entry) => entry.target.as_deref().is_some_and(|target| { target.starts_with("file://") || target.starts_with("./") @@ -513,8 +499,7 @@ impl Row { } } -/// What a slow plugin's footer says of its `report`: its costliest call kind and that kind's worst time, or its backlog. -/// The whole report goes in the row's details, so the footer leaves room for the title (PL-5). +/// Summarize the worst call or backlog in the footer; show the full report in details. fn slow_summary(report: &str) -> String { let Some(kinds) = report.strip_prefix("slow (p50/p99/worst): ") else { return "slow: backlog".to_owned() }; let worst = |kind: &str| -> Option<(String, f64)> { diff --git a/packages/cli-rs/crates/tui/src/plugins/notifications.rs b/packages/cli-rs/crates/tui/src/plugins/notifications.rs index 512a7e8e7c9..fd1dbe34483 100644 --- a/packages/cli-rs/crates/tui/src/plugins/notifications.rs +++ b/packages/cli-rs/crates/tui/src/plugins/notifications.rs @@ -1,7 +1,4 @@ -//! The notifications plugin (E.19a, row F09, `feature-plugins/system/notifications.ts`): asks for attention when -//! a session is done, a subagent is done, a form or a permission waits, or a session fails, and shows failures -//! as toasts. [`Tracker`] is the event logic; [`plugin`] feeds it the server's events. It is a plugin of the one API -//! (O-67). +//! Notify on session completion, pending requests, and failures. use std::cell::RefCell; use std::collections::HashSet; @@ -124,8 +121,7 @@ impl Tracker { self.terminal.remove(id); } V2Event::SessionExecutionSucceeded(event) => { - // A running subagent's report wakes the session again, so it isn't done yet. Subagent sounds stay - // as they were. + // A running child wakes its parent again; wait before reporting completion. let id = &event.data.session_id.0; if sessions.parent(id).is_some() || !sessions.running_child(id) { self.ended(id, sessions, &mut actions); diff --git a/packages/cli-rs/crates/tui/src/plugins/panel.rs b/packages/cli-rs/crates/tui/src/plugins/panel.rs index 28e07dd7b5c..d7d6f76f5c4 100644 --- a/packages/cli-rs/crates/tui/src/plugins/panel.rs +++ b/packages/cli-rs/crates/tui/src/plugins/panel.rs @@ -1,5 +1,4 @@ -//! The plugins' dialogs ([`abi::Dialog`]): a prompt, a list to pick from, a confirm, an alert, and a live panel, which changes in place while its key is open -//! (TS `/btw`'s `Answer`: the header, a body that scrolls, at most 60% of the screen high, and footer actions). +//! Host plugin dialogs and panels. A matching key updates a panel in place. use opencode_plugin::abi; use opencode_plugin::node::{self, Act}; @@ -51,7 +50,7 @@ fn max_rows(app: &App) -> u32 { type Owner = (String, u64); -/// Shows `dialog` of activation `generation` of plugin `id`, which owns it from now on. +/// Show `dialog` on behalf of plugin `id` at activation `generation`. pub fn show(tui: &Tui, id: &str, generation: u64, dialog: abi::Dialog) { let owner = (id.to_owned(), generation); match dialog { @@ -111,8 +110,7 @@ pub fn open(tui: &Tui, id: &str, key: &str) -> bool { mine && tui.dialogs.key() == Some(format!("{id}/{key}")) } -/// Closes the dialog plugin `id` opened, if it shows and the activation that opened it ended (4.14, deviation -/// `F16-plugin-dialog-ends-with-activation`). The dialogs replace each other, so the one on top is the only one. +/// Close a plugin dialog only when its owning activation ends. pub fn close(tui: &Tui, id: &str) { let owner = tui.reads.owner.borrow().clone(); if owner.is_some_and(|(owner, generation)| owner == id && !tui.plugins.owns(id, generation)) { @@ -156,9 +154,7 @@ fn ask(tui: &Tui, owner: Owner, asked: abi::Prompt) { tui.dialogs.clear(); run(&tui, &owner, &action, Some(value)); }); - // TS draws the description as a text of its own above the field (`{description}`), in - // OpenTUI's default text color; here in the color of the host's own prompt descriptions, over a few - // rows, so the field stays on screen. + // Use the default text color for prompt descriptions. let description = description.clone().map(|text| { Rc::new(move |cx: &DialogCx| { Text::new(&cx.app, &*text).fg(cx.theme.text.muted).max_height(DESCRIPTION_ROWS).as_any() @@ -190,8 +186,7 @@ fn bounded(text: &str) -> &str { &text[..text.floor_char_boundary(opencode_plugin::limits::get().text as usize)] } -/// The rich select on screen (synthesis 4.10): the select the plugin showed last, which a select of the same key -/// replaces in place, keeping the filter and the selected row. +/// Update a select with the same key in place so the filter and selection survive. pub struct Picker { key: String, owner: RefCell, @@ -342,7 +337,7 @@ fn list(tui: &Tui, owner: Owner, select: abi::Select, kept: Option<(String, Opti handle.move_to(&selected); } } - // The first footer was drawn before the hints could see the selection. + // Refresh hints once the first selection is available. handle.refresh_footer(); view }, else View::new(&cx.app)), @@ -359,8 +354,7 @@ fn styled(app: &App, theme: &opencode_ui::theme::Theme, span: &abi::Span) -> Tex Text::new(app, span.text.clone()).fg(fg) } -/// What a select with a query does as its filter changes (P6c): once the text has stayed the select's delay, its action -/// runs with the text, as TS's debounced `onFilter` (`createDebouncedSignal`). +/// Debounce filter changes before invoking the query action. fn query(tui: &Tui, picker: &Rc) -> Rc { let (weak, timer) = (Rc::downgrade(picker), Rc::new(Cell::new(None::))); Rc::new(bind!(tui.weak(), |tui, text: &str| { @@ -446,7 +440,7 @@ impl Picker { return; }; if let Some(plugin) = &option.toggle { - // Only the user toggles a plugin: a key or a click, never a run of the command by name (synthesis 3.6). + // Only a user key or click may toggle a plugin. let by_input = self.handle.borrow().as_ref().is_some_and(|handle| handle.by_input()); if !by_input { log::warn!("plugin {}: a row toggles a plugin only on a key or a click", owner.0); @@ -461,8 +455,7 @@ impl Picker { run(tui, &owner, action, Some(value)); } - /// Enables or disables `plugin` for the row of `value`, as the host does (synthesis 3.6): never the caller itself - /// or the plugin manager, after the key is handled, and only if the row still names that plugin then. + /// Toggle the entry selected by `value`. Refuse changes to the calling plugin or the active manager. fn toggle(self: &Rc, tui: &Tui, value: &str, plugin: &str) { let caller = self.owner.borrow().0.clone(); if toggled(tui, &caller, plugin).is_none() { @@ -485,8 +478,7 @@ impl Picker { Some((entry, Toggle::Switch(active))) => (entry, active), // The host's question, after which the list comes back on the row, unless a dialog replaced it. Some((_, Toggle::Ask(target))) => { - // The question replaces the select, which then holds the picker no more. The row's own action - // asks its plugin for the list as it is now (review bigboi-5); without one, the list as it was. + // Approval replaces the select; reopen the list through its owning plugin to get fresh rows. let (shown, value) = (picker.shown.borrow().clone(), value.clone()); let then = shown.options.iter().find(|option| option.value == value).and_then(|row| row.action.clone()); @@ -521,7 +513,7 @@ impl Picker { Some(Ok(())) => {} } tui.navigate(tui.route()); - // The hints say what the registry holds now; the rows are the plugin's, which hears of the change. + // Read hints from the current registry; the plugin supplies its own rows. if let Some(handle) = picker.handle.borrow().clone() { handle.refresh_footer(); } @@ -541,13 +533,13 @@ enum Toggle { fn toggled(tui: &Tui, caller: &str, name: &str) -> Option<(opencode_plugin::Entry, Toggle)> { let entries = tui.plugins.entries(); let plugin = opencode_plugin::Entry::plugin_key(name); - // A target names the entry it is now: a project's build keeps its target once approved (review carbon-2). + // Resolve the current entry by target across approval. let entry = entries .iter() .find(|entry| entry.key == name) .or_else(|| entries.iter().find(|entry| entry.key == plugin)) .or_else(|| entries.iter().find(|entry| entry.target.as_deref() == Some(name)))?; - // Never the caller or the manager that runs: a held build of their ID is another plugin (review carbon-3). + // Reject the active caller and manager, not unrelated held builds with the same ID. let refused = [opencode_plugin::Entry::plugin_key(caller), opencode_plugin::Entry::plugin_key(super::manager::ID)]; if refused.contains(&entry.key) { return None; @@ -615,7 +607,6 @@ fn actions(tui: &Tui, picker: &Rc) -> Vec Group::Primary, false => Group::Secondary, @@ -663,9 +654,7 @@ fn actions(tui: &Tui, picker: &Rc) -> Vec bool { let command = action .command @@ -678,8 +667,7 @@ fn usable_action(tui: &Tui, action: &abi::SelectAction) -> bool { usable } -/// Whether `key` parses as keys of the host's keymap and holds neither the reserved chord nor escape: the dialog's two -/// close keys, which a plugin's layer above them would take, keeping the user in its dialog (review carbon-5). +/// Reject Escape and the reserved chord so a plugin cannot trap the user in a dialog. fn usable_key(tui: &Tui, key: &str) -> bool { let keymap = tui.keymap.keymap(); let closing: Vec<_> = ["escape", opencode_plugin::abi::interact::RESERVED] @@ -732,7 +720,7 @@ fn detail(tui: &Tui, owner: Owner, details: abi::ErrorDetails) { run(&tui, &owner, back, None); } })); - // A TUI plugin's own error, which only the host reads (review bigboi-2). + // Only the host may read another plugin's error text. let error = details.plugin.as_deref().and_then(|key| plugin_error(&tui, key)); let props = crate::dialogs::error_details::Props { title: details.title.clone(), @@ -788,7 +776,7 @@ fn ask_yes(tui: &Tui, owner: Owner, confirm: abi::Confirm) { tui.dialogs.set_centered(centered); } -/// TS `dialog.alert`: however the alert closes, its action runs once after. +/// Run the alert action once after dismissal, regardless of how it closes. fn tell(tui: &Tui, owner: Owner, alert: abi::Alert) { let (size, centered) = (alert.size.map(dialog_size).unwrap_or_default(), alert.centered); let props = AlertProps { title: alert.title, message: alert.message, on_confirm: None }; @@ -809,9 +797,7 @@ fn tell(tui: &Tui, owner: Owner, alert: abi::Alert) { tui.dialogs.set_centered(centered); } -/// A plugin's dialog surface on screen (TS `ui.dialog.show`): the frame, with a header when it has a title, and in its -/// body the mount of the plugin's surface, which ends as the dialog closes. Built again in a new theme, it keeps its -/// widgets and the mount. +/// Host frame and mounted body for a plugin dialog surface. pub struct Body { key: String, /// The key the plugin named, which the mount's ID has. @@ -821,8 +807,7 @@ pub struct Body { title: RefCell>, frame: View, header: View, - /// The body's bounded scroll, which holds the body while it is taller than the room the screen leaves: it then - /// scrolls, and a focused node in it shows. A body that fits sits in the frame itself, laid out as TS's. + /// Scroll an oversized body within the screen and reveal its focused node. scroll: ScrollBox, /// The rows the screen leaves the body, and whether the scroll holds it. room: Cell, @@ -844,7 +829,7 @@ fn surface(tui: &Tui, owner: Owner, shown: abi::DialogSurface) { let (size, centered) = (shown.size.map(dialog_size).unwrap_or_default(), shown.centered); let open = open(tui, &owner.0, shown.shown_key()).then(|| tui.reads.surface.borrow().clone()).flatten(); if let Some(body) = open.filter(|body| body.key == key && body.surface == shown.surface) { - // A request that changes it in place and waits for its close hears it too (big-boi ds-10). + // In-place updates that wait for dismissal must receive it too. let dismissed = tui.reads.dismissed.borrow_mut().take().filter(|(of, _)| *of == owner); body.dismissed.borrow_mut().extend(dismissed); *body.owner.borrow_mut() = owner.clone(); @@ -867,7 +852,7 @@ fn surface(tui: &Tui, owner: Owner, shown: abi::DialogSurface) { } let app = &tui.app; let (header, body) = (View::new(app), View::new(app).column().focusable(true)); - // As high as the body, up to the screen's room: a taller body scrolls rather than leaving the screen (big-boi ds-9). + // Bound the scroll height to the available screen space. let scroll = ScrollBox::new(app) .scrollbar_colors(Color::rgb(0x9a, 0x9e, 0xa3), Color::rgb(0x25, 0x25, 0x27)) .min_height(0) @@ -917,8 +902,7 @@ fn surface(tui: &Tui, owner: Owner, shown: abi::DialogSurface) { if mine { tui.reads.surface.borrow_mut().take(); } - // The mount ends now, so nothing it asked for after the close goes out; its handler hears it closed, as - // the plugin's call, after the event that closed it. + // End the mount before dispatching its close callback so stale requests cannot escape. let body = closed.upgrade(); let mount = body.as_ref().and_then(|body| body.mount.borrow_mut().take()); if let Some(tell) = mount.and_then(opencode_plugin::PanelMount::close) { @@ -956,9 +940,7 @@ pub fn reveal(tui: &Tui, widget: &AnyWidget) { } } -/// A reload of plugin `id`'s registrations ended the mount of its dialog surface on screen: the dialog stays and mounts -/// again from the registration that replaced it, under the same key, so the JS host adopts what it rendered, as a -/// panel does (CT-29). Its handler hears no close. +/// Remount an open dialog against the plugin's replacement registration. pub fn remount(tui: &Rc, id: &str) { let Some(body) = tui.reads.surface.borrow().clone() else { return }; if body.owner.borrow().0 != id || !open(tui, id, &body.named) || !tui.plugins.has_dialog(id, &body.surface) { @@ -968,8 +950,7 @@ pub fn remount(tui: &Rc, id: &str) { body.body.clear(); let host = super::host::host(tui); let new = tui.plugins.dialog(&*host, id, &body.surface, &body.named, &body.body); - // What the user typed stays, with the caret: the plugin keeps its components, and an uncontrolled field's value is - // the host's (big-boi ds-2). + // Preserve the user's draft and caret when remounting an uncontrolled field. if let (Some(old), Some(new)) = (&old, &new) { old.hand_over(new); } @@ -982,8 +963,7 @@ impl Body { fn build(self: &Rc, tui: &Rc, cx: &Rc) -> View { *self.cx.borrow_mut() = Some(cx.clone()); self.draw_header(); - // Built again in a new theme, the frame is put back: the node of the body that had the focus takes it again - // (big-boi ds-6). + // Restore focus to the same body node after a theme rebuild. let frame = self.frame.id(); let focused = tui.app.focused().filter(|widget| { std::iter::successors(Some(widget.clone()), |widget| widget.parent()).any(|widget| widget.id() == frame) @@ -1162,8 +1142,7 @@ fn build(tui: &Tui, cx: &Rc, key: String, owner: Owner, panel: abi::Pa let set = |app: &App, height: u16| u32::from(height).min(u32::from(app.size().1).saturating_sub(6)).max(1); let scroll = ScrollBox::new(app).scrollbars(false).height(panel.height.map_or(1, |height| set(app, height))); let content = View::new(app).shrink(0.0); - // A bare panel is the dialog's frame and its body, which no box sizes or scrolls (TS `Dialog` around a plugin's - // own view); its header and footer are built and never shown. + // A bare panel supplies its own body sizing and scrolling. let fitted = !panel.bare; if fitted { scroll.add(&content); @@ -1176,7 +1155,7 @@ fn build(tui: &Tui, cx: &Rc, key: String, owner: Owner, panel: abi::Pa false => View::new(app).child(&scroll), }; let footer = View::new(app); - // A panel of a set height without actions has no footer row (TS `DialogLayout` without a footer). + // A fixed-height panel with no actions needs no footer. let footed = panel.height.is_none() || !panel.actions.is_empty(); let layout = match fitted { true => dialog::layout_view(cx, &header, &body, footed.then_some(&footer), DIALOG_INSET, 1), @@ -1349,7 +1328,7 @@ impl Live { &act, &mut hovers, &|text| { - // As in TS, of the plugins' Markdown only the `/btw` answer links sessions (`btw.tsx`). + // Only `/btw` answers resolve session links in plugin Markdown. if self.owner.0 != super::btw::ID { return tui.markdown(text).as_any(); } @@ -1380,9 +1359,7 @@ impl Live { } } -/// Runs `owner`'s `action` once the current event is handled; `value`, a prompt's text, is its input. An action whose -/// activation ended before then reaches nothing, not the build that replaced it (review carbon-pt-1), unless the -/// activation that replaced it goes on from it (a reload of a JS plugin's registrations, FT-4). +/// Defer the action until after the current event. Discard it if its owning activation has ended. fn run(tui: &Tui, owner: &Owner, action: &abi::Action, value: Option<&str>) { let abi::Action::Command { name, input } = action.clone(); let input = value.map(str::to_owned).or(input); diff --git a/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs b/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs index 727164ac6da..dbd630d4c31 100644 --- a/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/prompt_footer.rs @@ -1,12 +1,4 @@ -//! The prompt footer plugin (E.14, row F02, `feature-plugins/prompt/footer.tsx`), appended to `prompt.footer`: -//! -//! - the running subagents and shells of the session (a click opens the first child), its goal (`goal.rs`), -//! and its context use and cost, as far as they fit; -//! - otherwise the `agents` and `commands` hints, which read as disabled while the session pane does not own the input; -//! - in shell mode, `esc exit shell mode`. -//! -//! It is a plugin of the one API (O-67), on contract 2.0 (P6a). Each mount of a session's footer counts in [`Goals`], -//! which reads the goal: the surface hears its mounts begin and end ([`Event::Mount`]). +//! Prompt footer for session activity, hints, and status. use opencode_plugin::abi::interact::{Event, Handled}; use opencode_plugin::abi::v2::{Node, Place, Surface}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs index 94ffe23e4c2..d96c1414ec6 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_context.rs @@ -1,6 +1,4 @@ -//! The sidebar's context section (E.14, row F04, `feature-plugins/sidebar/context.tsx`): the tokens of the last -//! reply, the share of the model's context they use, and the session's cost. It is a plugin of the one API (O-67), -//! on contract 2.0 (P6a). [`Last`] and [`money`] also serve the prompt footer. +//! Sidebar context usage and cost for the session family. use std::cell::RefCell; @@ -106,8 +104,7 @@ impl Last { self.models = self.location.as_ref().and_then(|location| read.models(Some(location))); } let mut stale = models || changed.list(&self.session); - // A message changed in place from the usage's source on moves the usage only if what it reads of it changed: - // each such message is read alone, so a streamed delta costs one message and not the session (P6a review). + // Re-read only changed messages that can affect usage; streamed text alone does not invalidate the total. for (session, id) in &changed.messages { if stale { break; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs index a570e19cba0..401f4bf0f89 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_footer.rs @@ -1,7 +1,4 @@ -//! The sidebar footer (E.14, row F08, `feature-plugins/sidebar/footer.tsx`): the "Getting started" card while -//! no provider is connected and it was not dismissed (from 22 rows), then the location as `directory:branch`, -//! which brightens under the pointer and opens the working directory menu (E.20) on a click. It is a plugin of the -//! one API (O-67), on contract 2.0 (P6a). +//! Sidebar footer with the session location and dismissible getting-started card. use opencode_plugin::abi::v2::{Node, Place, Surface}; use opencode_plugin::abi::{self, Click, Command, Justify, Layout, Placement, Span, Wrap}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs index e3b7817c3ad..6ef6decc0de 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_limit.rs @@ -1,6 +1,4 @@ -//! The sidebar's limit section (E.14, row F05, `feature-plugins/sidebar/limit.tsx`): what the OpenCode Console -//! workspace's limits leave for the selected model, in the error color when it is out or reached. Hidden when -//! no limit applies to the model. It is a plugin of the one API (O-67), on contract 2.0 (P6a). +//! Sidebar warning for the selected model's remaining workspace allowance. use opencode_plugin::abi::v2::{Node, Place, Surface}; use opencode_plugin::abi::{self, Placement, Span}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs index 8c54518f896..47ca9d86813 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_mcp.rs @@ -1,7 +1,4 @@ -//! The sidebar's MCP section (E.14, row F06, `feature-plugins/sidebar/mcp.tsx`): each server of the session's -//! location with its status. Above two servers the header folds the list, and the folded header counts the -//! active servers and the errors. A click on a server opens the MCP dialog on it, and on its error when it failed -//! (`mcp.list` with the server's name). It is a plugin of the one API (O-67), on contract 2.0 (P6a). +//! Foldable MCP status list for the session's location. use opencode_api::generated::McpServer; use opencode_plugin::abi::v2::{Node, Place, Surface}; diff --git a/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs b/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs index cfbdeae86a6..7cc5973f9c1 100644 --- a/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs +++ b/packages/cli-rs/crates/tui/src/plugins/sidebar_todo.rs @@ -1,6 +1,4 @@ -//! The sidebar's todo section (E.14, row F07, `feature-plugins/sidebar/todo.tsx`): the list of the latest -//! completed `todowrite` call before the revert boundary. Above two items the header folds the list, and the -//! folded header counts what remains. It is a plugin of the one API (O-67), on contract 2.0 (P6a). +//! Show the most recent completed todo list before the revert boundary. use opencode_api::generated::{SessionMessageAssistantContentItem, SessionMessageAssistantToolState}; use opencode_plugin::abi::v2::{Node, Place, Surface}; @@ -61,8 +59,7 @@ struct Last { } impl Last { - /// Reads what `changed` may have changed; whether the list it shows changed. A streamed delta that leaves the - /// latest `todowrite` call as it was allocates nothing. + /// Refresh the displayed list only when a relevant message or boundary changes. fn update(&mut self, read: &dyn abi::Read, changed: &Changed, fresh: bool) -> bool { let info = fresh || changed.session(&self.session); if info { @@ -70,8 +67,7 @@ impl Last { read.session(&self.session).and_then(|session| session.info.revert).map(|revert| revert.message_id.0); } let mut messages = info || changed.list(&self.session); - // A message changed in place can change the list only if it holds a `todowrite` call or held the one the list - // came from: each is read alone, so a streamed delta costs one message and not the session (P6a review). + // Inspect changed messages individually; unrelated deltas must not rescan the transcript. for (session, id) in &changed.messages { if messages { break; diff --git a/packages/cli-rs/crates/tui/src/plugins/stats.rs b/packages/cli-rs/crates/tui/src/plugins/stats.rs index 22c7403f4bc..24ec5dc1c78 100644 --- a/packages/cli-rs/crates/tui/src/plugins/stats.rs +++ b/packages/cli-rs/crates/tui/src/plugins/stats.rs @@ -1,4 +1,4 @@ -//! TypeScript: `feature-plugins/system/stats.tsx`, `stats-data.ts`. +//! Session statistics poster. use opencode_api::client::Client; use opencode_api::generated::{ExperimentalSessionStatsInput, ExperimentalSessionStatsInputTools, SessionStatsInfo}; @@ -45,11 +45,10 @@ fn setup(setup: &mut abi::Setup) -> Result<(), String> { Some(Err(_)) => Node::text([Span::new("Could not load stats. Reopen /stats to try again.")]) .fg("text.feedback.error.base"), }; - // The terminal's height, as the poster reads it: on a resize the host's watch calls the view before a layout - // gives the route its new room, so the input's is the last frame's (review carbon-1). + // Use the terminal height during resize; the view notification precedes layout of the new route size. page(node, cx.read.info().size.1) }); - // As TS's `StatsPage` resource: each mount asks afresh, and a reply after the route went is dropped. + // Fetch on each mount and discard replies after unmount. let mounted = state.clone(); // The calendar and the logo compute their colors from the theme's, so a theme change calls the view (the 1.x route // rendered again on one). @@ -124,7 +123,7 @@ const DIGITS: [(char, [&str; 5]); 15] = [ ('T', ["111", "010", "010", "010", "010"]), ]; -/// The page's scroll, which keeps where it was scrolled while the route shows. +/// Stable key for the page's scroll offset. const PAGE: &str = "page"; fn page(content: Node, height: u16) -> Node {