Skip to main content

sapphire_framework_server/
command.rs

1//! The framework-provided half of an application's CLI.
2
3use std::fmt::Write as _;
4use std::path::PathBuf;
5use std::sync::Arc;
6
7use corundum_framework_service::{Environment, ServiceCommand, SystemManager};
8use sapphire_backend::protocol as proto;
9use sapphire_bridge_client::BridgeClient;
10use sapphire_ipc::{ClientInfo, Endpoint};
11
12use crate::AppServer;
13use crate::error::{Error, Result};
14use crate::selection::SelectionFile;
15use crate::settings::{AppSettings, Settings};
16use sapphire_workspace::AppContext;
17
18mod config;
19
20pub use config::{AppConfigCommand, AppScopeFlags};
21
22pub use sapphire_backend::protocol::{StatusReport, StatusRow};
23
24/// The framework's commands, flattened into an application's CLI (spec decision 2).
25///
26/// An application composes these beside its own verbs by giving its subcommand enum a
27/// `#[command(flatten)] Framework(FrameworkCommand)` variant, so every verb — the app's and
28/// the framework's — sits at the same top level. The parse tests below pin that shape.
29///
30/// A desktop app's binary carries the same enum (#366): it is the CLI as well, so the CLI
31/// version is a subset of it. Its subcommand is optional, and with none it opens the
32/// window; the CLI version's is required, so a bare invocation prints the help. The verbs
33/// are one definition either way:
34///
35/// ```rust,ignore
36/// #[derive(clap::Parser)]
37/// struct Desktop {
38///     #[command(subcommand)]
39///     command: Option<Command>, // `Command` for the CLI version
40/// }
41///
42/// match Desktop::parse().command {
43///     None => open_the_window(),
44///     Some(command) => runtime.block_on(run(command)),
45/// }
46/// ```
47#[derive(Debug, clap::Subcommand)]
48pub enum FrameworkCommand {
49    /// Run the server in this process until SIGTERM or SIGINT.
50    Serve,
51    /// Report whether a server is running, and which version.
52    Status,
53    /// Install, remove or report this application's operating-system service.
54    #[command(subcommand)]
55    Service(ServiceCommand),
56    /// Replace this executable with the newest release, then do the same for
57    /// `sapphire-bridge` (unless `--no-bridge`). Restart the services afterwards to run
58    /// them.
59    Update(AppUpdateArgs),
60    /// Create, select, show and map this application's workspace. The server serves one
61    /// at a time.
62    #[command(subcommand)]
63    Workspace(WorkspaceCommand),
64    /// Add, list, retire, restore and rotate the API keys of the workspace this application
65    /// serves — for clients that reach it over HTTP. Works on the workspace's files, with or
66    /// without a running server; the keys sync with the workspace.
67    #[command(subcommand)]
68    ApiKey(corundum_framework_keys::KeyCommand),
69    /// Renamed to `api-key` (#364).
70    #[command(hide = true)]
71    ExternalDevice(LegacyExternalDevice),
72    /// List, show, set and unset this application's settings and the bridge's, by key.
73    /// Without a running server, this application's own, on its files.
74    #[command(subcommand)]
75    Config(AppConfigCommand),
76    /// Serve this application's tools to an AI agent over MCP on stdin/stdout. Talks to the
77    /// running server, which it does not start; register this command with the agent.
78    #[cfg(feature = "mcp")]
79    Mcp,
80}
81
82impl FrameworkCommand {
83    /// Carry out the command, returning the process exit code.
84    ///
85    /// The application matches its own variants first, then hands the framework's here,
86    /// with what [`serve_restarting`](crate::serve_restarting) takes: its context, its own
87    /// settings (`()` for none) and the function that builds its server from the settings.
88    /// `serve` runs [`serve_restarting`](crate::serve_restarting); the commands that need an
89    /// [`AppServer`] — `service`, `update` and `mcp` — read the settings and call `build`
90    /// once; `config` reads and writes the settings through the running server, or the
91    /// files themselves when none runs.
92    ///
93    /// ```rust,ignore
94    /// command
95    ///     .dispatch(&CTX, MyOwner, |settings: &Settings| AppServer::new(&CTX, VERSION), VERSION)
96    ///     .await
97    /// ```
98    pub async fn dispatch<A, F>(
99        self,
100        ctx: &'static AppContext,
101        owner: A,
102        build: F,
103        version: &'static str,
104    ) -> Result<i32>
105    where
106        A: AppSettings + Clone,
107        F: Fn(&Settings) -> AppServer,
108    {
109        let app = ctx.app_name;
110        // Built only by the commands that need a server, and then once. These are the way
111        // out of a bad release or a broken install, so settings that cannot be read are
112        // warned about and replaced by the defaults rather than stopping them.
113        let server = |owner: A| -> Result<AppServer> {
114            Ok(build(&settings_or_defaults(ctx, Arc::new(owner))?))
115        };
116        match self {
117            FrameworkCommand::Serve => {
118                crate::serve_restarting(ctx, owner, build).await?;
119                Ok(0)
120            }
121            FrameworkCommand::Status => {
122                let endpoint = Endpoint::for_app(app)?;
123                run_status(&endpoint, app, version).await
124            }
125            FrameworkCommand::Service(command) => {
126                let spec = server(owner)?.service_spec();
127                command
128                    .run(&spec, &Environment::detect(), &SystemManager)
129                    .map_err(Error::from)
130            }
131            FrameworkCommand::Update(args) => {
132                let server = server(owner)?;
133                let own = match server.release_source() {
134                    Some(source) => {
135                        sapphire_framework_update::run(&args.update, source, app, version)
136                            .await
137                            .map_err(Error::from)
138                    }
139                    None => {
140                        println!("{app} does not say where its releases are");
141                        Ok(1)
142                    }
143                };
144                // The bridge is updated whatever became of the app: one is independent of
145                // the other, and an app installed with cargo still has a released bridge.
146                let bridge = if args.no_bridge {
147                    0
148                } else {
149                    update_bridge(&args.update).await?
150                };
151                Ok(own?.max(bridge))
152            }
153            FrameworkCommand::Config(command) => config::config(ctx, owner, command, version).await,
154            FrameworkCommand::Workspace(command) => command.dispatch(app, version).await,
155            FrameworkCommand::ApiKey(command) => {
156                api_key(ctx, &server(owner)?.profiles().list(), command)
157            }
158            FrameworkCommand::ExternalDevice(legacy) => {
159                eprintln!("warning: `external-device` is renamed to `api-key`");
160                if !legacy.app.is_empty() {
161                    eprintln!(
162                        "API keys are per workspace now, not per application: `--app` is not taken"
163                    );
164                    return Ok(2);
165                }
166                api_key(ctx, &server(owner)?.profiles().list(), legacy.command)
167            }
168            #[cfg(feature = "mcp")]
169            FrameworkCommand::Mcp => {
170                server(owner)?.serve_mcp_stdio(version).await?;
171                Ok(0)
172            }
173        }
174    }
175}
176
177/// `ctx`'s application's settings, or — when they cannot be read — every key at its
178/// default, after one warning on stderr naming the device file and the error.
179///
180/// For `update`, `service` and `mcp`, which must work whatever the files hold: `update` is
181/// the way out of a bad release, and `service uninstall` must always be possible.
182fn settings_or_defaults(ctx: &AppContext, owner: Arc<dyn AppSettings>) -> Result<Settings> {
183    match Settings::load(ctx, Arc::clone(&owner)) {
184        Ok(settings) => Ok(settings),
185        Err(err) => {
186            let file = Settings::device_file(ctx)
187                .map_or_else(|| "the settings".to_owned(), |f| f.display().to_string());
188            eprintln!("warning: could not read {file} ({err}); going on with the default settings");
189            Settings::defaults(ctx, owner)
190        }
191    }
192}
193
194/// `update`'s arguments in an application: its own, and whether the bridge follows.
195#[derive(Clone, Debug, Default, clap::Args)]
196pub struct AppUpdateArgs {
197    /// `--check` and `--yes`, for the application and the bridge alike.
198    #[command(flatten)]
199    pub update: sapphire_framework_update::UpdateArgs,
200    /// Update this application alone, leaving `sapphire-bridge` as it is.
201    #[arg(long)]
202    pub no_bridge: bool,
203}
204
205/// The bridge's executable, as it is installed beside the apps.
206const BRIDGE_BINARY: &str = "sapphire-bridge";
207
208/// Where the bridge's releases are, for a bridge too old to update itself.
209const BRIDGE_RELEASES: &str = "https://github.com/sapphire-turtle/sapphire-framework/releases";
210
211/// The first `name` (with the platform's executable suffix) in the directories of `path`.
212fn find_on_path(name: &str, path: Option<&std::ffi::OsStr>) -> Option<PathBuf> {
213    let file = format!("{name}{}", std::env::consts::EXE_SUFFIX);
214    std::env::split_paths(path?)
215        .map(|dir| dir.join(&file))
216        .find(|candidate| candidate.is_file())
217}
218
219/// Run the bridge on `PATH`'s own `update` with `args`; returns its exit code. No bridge on
220/// `PATH` is nothing to update. `update` does it after the application; a desktop package,
221/// whose own update ends the process, does it first (#357).
222pub async fn update_bridge(args: &sapphire_framework_update::UpdateArgs) -> Result<i32> {
223    match find_on_path(BRIDGE_BINARY, std::env::var_os("PATH").as_deref()) {
224        Some(exe) => run_bridge_update(&exe, args).await,
225        None => {
226            println!("{BRIDGE_BINARY} is not on PATH; not updating it");
227            Ok(0)
228        }
229    }
230}
231
232/// Run the bridge at `exe`'s own `update` with `args`; returns its exit code.
233///
234/// The bridge updates itself rather than being replaced from here: it knows its own
235/// version and where it was installed from, and replacing a running executable is its own
236/// business on every platform.
237async fn run_bridge_update(
238    exe: &std::path::Path,
239    args: &sapphire_framework_update::UpdateArgs,
240) -> Result<i32> {
241    // A bridge from before `update` rejects the subcommand.
242    let knows_update = tokio::process::Command::new(exe)
243        .args(["update", "--help"])
244        .stdout(std::process::Stdio::null())
245        .stderr(std::process::Stdio::null())
246        .status()
247        .await?
248        .success();
249    if !knows_update {
250        println!(
251            "{} cannot update itself; install the newest from {BRIDGE_RELEASES}",
252            exe.display()
253        );
254        return Ok(1);
255    }
256    let mut command = tokio::process::Command::new(exe);
257    command.arg("update");
258    if args.check {
259        command.arg("--check");
260    }
261    if args.yes {
262        command.arg("--yes");
263    }
264    // Inherited stdio: the bridge asks its own question and says what it did.
265    let status = command.status().await?;
266    Ok(status.code().unwrap_or(1))
267}
268
269/// The `workspace` subcommands (#215: one workspace per server).
270///
271/// `init`, `select`, `sync`, `move` and `remove` go to the app's server over IPC,
272/// because the server owns the marker directories, the sync ids and which workspace it
273/// serves; `show` asks the server for its workspace and then the bridge for the workgroup's
274/// ledger. `init --remote-workspace` has the server resolve the name through the bridge.
275#[derive(Debug, clap::Subcommand)]
276pub enum WorkspaceCommand {
277    /// Create this app's workspace home in the given directory, and switch the server to it.
278    Init {
279        /// Where the workspace root goes, created if missing. Defaults to the app's
280        /// default workspace, `<data dir>/workspaces/default`.
281        dir: Option<PathBuf>,
282        /// Also start syncing it, which publishes it into the workgroup ledger.
283        #[arg(long)]
284        sync: bool,
285        /// Sync it as this workspace of the workgroup, by name or id, instead of as a new
286        /// one: its files and settings arrive from the other devices.
287        #[arg(long, value_name = "NAME|ID", requires = "sync")]
288        remote_workspace: Option<String>,
289    },
290    /// Switch the server to an existing workspace of this app.
291    Select {
292        /// The workspace's root. Defaults to the app's default workspace,
293        /// `<data dir>/workspaces/default`.
294        dir: Option<PathBuf>,
295        /// Also start syncing it, which publishes it into the workgroup ledger. A
296        /// workspace that has synced before turns sync back on by itself.
297        #[arg(long)]
298        sync: bool,
299    },
300    /// Turn sync on or off for the server's workspace, or show its sync state.
301    #[command(subcommand)]
302    Sync(WorkspaceSyncCommand),
303    /// Show the server's workspace, then the workgroup's workspaces of this app.
304    Show,
305    /// Move the server's workspace folder to a new path on this host, keeping its sync.
306    Move {
307        /// The new root. It must not exist yet; its parent must.
308        dir: PathBuf,
309    },
310    /// Stop serving the server's workspace on this host. Other devices keep their copies.
311    Remove {
312        /// Also delete the workspace's folder and every file in it.
313        #[arg(long)]
314        delete: bool,
315    },
316}
317
318impl WorkspaceCommand {
319    /// Carry out the command, returning the process exit code.
320    ///
321    /// `app` names the endpoint to open (`Endpoint::for_app`); `version` is this
322    /// process's own, for the handshake.
323    pub async fn dispatch(self, app: &'static str, version: &'static str) -> Result<i32> {
324        match self {
325            WorkspaceCommand::Init {
326                dir,
327                sync,
328                remote_workspace,
329            } => workspace_init(app, version, dir, sync, remote_workspace).await,
330            WorkspaceCommand::Select { dir, sync } => {
331                workspace_select(app, version, dir, sync).await
332            }
333            WorkspaceCommand::Sync(command) => workspace_sync(app, version, command).await,
334            WorkspaceCommand::Show => workspace_show(app, version).await,
335            WorkspaceCommand::Move { dir } => workspace_move(app, version, dir).await,
336            WorkspaceCommand::Remove { delete } => workspace_remove(app, version, delete).await,
337        }
338    }
339}
340
341/// The `workspace sync` subcommands: the server's workspace's sync, switched after the fact.
342#[derive(Debug, clap::Subcommand)]
343pub enum WorkspaceSyncCommand {
344    /// Start syncing the server's workspace, which publishes it into the workgroup ledger.
345    Enable,
346    /// Stop syncing the server's workspace on this host. It keeps its sync id, so enabling
347    /// it again picks up where it left off; other devices keep their copies.
348    Disable,
349    /// Show the server's workspace's sync state.
350    Status,
351}
352
353/// `external-device …`, kept one release as a hidden alias of `api-key`.
354#[derive(Debug, clap::Args)]
355pub struct LegacyExternalDevice {
356    /// What `external-device add --app` took; refused, as keys are per workspace now.
357    #[arg(long = "app", global = true, hide = true)]
358    app: Vec<String>,
359    #[command(subcommand)]
360    command: corundum_framework_keys::KeyCommand,
361}
362
363/// `api-key …`: on the files of the workspace this application serves, as its selection
364/// file records it. No workspace selected → a line naming `workspace select`, exit 1.
365/// `add --profile` takes one of `profiles`.
366fn api_key(
367    ctx: &AppContext,
368    profiles: &[sapphire_framework_keys::Profile],
369    command: corundum_framework_keys::KeyCommand,
370) -> Result<i32> {
371    let Some(selection) = SelectionFile::for_app(ctx).load(ctx.app_name)? else {
372        eprintln!(
373            "{} serves no workspace yet: choose one with `{} workspace select <dir>`",
374            ctx.app_name, ctx.app_name
375        );
376        return Ok(1);
377    };
378    // Opening the store creates its directory: never recreate a workspace that moved away.
379    if !selection.root.join(format!(".{}", ctx.app_name)).is_dir() {
380        eprintln!(
381            "the workspace at {} is not reachable: bring it back, or choose another with `{} workspace select <dir>`",
382            selection.root.display(),
383            ctx.app_name
384        );
385        return Ok(1);
386    }
387    let run = sapphire_framework_keys::open_store(ctx.app_name, &selection.root)
388        .and_then(|mut store| command.run(&mut store, profiles));
389    match run {
390        Ok(code) => Ok(code),
391        Err(err) => {
392            eprintln!("{err}");
393            Ok(1)
394        }
395    }
396}
397
398/// `workspace init`: the server does the creating, over IPC.
399///
400/// The server owns the marker, the registry and the sync ids, so a workspace created
401/// here is one the server already knows and a GUI sharing the registry sees. Nothing is
402/// listening → the one line and exit 1; nothing is ever started (Global Constraints).
403/// `--sync` rides the server's existing `sync.enable` path on the same connection, and
404/// its state is printed after, so an unjoined host's "no workgroup knows it yet" is
405/// plain.
406///
407/// `--remote-workspace` goes to `sync.map` instead, which makes the marker and takes the
408/// workgroup's identity in one step: the workspace's `config.toml` is the one that
409/// arrives, not one written here first (#253).
410async fn workspace_init(
411    app: &'static str,
412    version: &'static str,
413    dir: Option<PathBuf>,
414    sync: bool,
415    remote_workspace: Option<String>,
416) -> Result<i32> {
417    let endpoint = Endpoint::for_app(app)?;
418    let client_info = ClientInfo {
419        kind: "cli".to_owned(),
420        version: version.to_owned(),
421        api: proto::API_VERSION,
422        app_api: None,
423        pid: std::process::id(),
424    };
425    let Some((client, _)) = sapphire_ipc::connect_or_absent(&endpoint, app, client_info).await?
426    else {
427        println!("no {app} server is running");
428        return Ok(1);
429    };
430
431    let dir = workspace_dir(app, dir)?;
432    if let Some(selector) = remote_workspace {
433        // `sync.map` needs the folder; `workspace.init` makes its own.
434        std::fs::create_dir_all(&dir)?;
435        let mapped: proto::SyncEnableResult = client
436            .call(
437                proto::SYNC_MAP,
438                proto::SyncMapParams {
439                    workspace: selector.clone(),
440                    dir: dir.clone(),
441                },
442            )
443            .await?;
444        println!(
445            "initialized {app} workspace in {} from {selector}",
446            dir.display()
447        );
448        println!(
449            "the {app} server now serves it, syncing as {}",
450            mapped.workspace_id
451        );
452        return Ok(0);
453    }
454    let result: proto::WorkspaceInitResult = client
455        .call(proto::WORKSPACE_INIT, proto::WorkspaceInitParams { dir })
456        .await?;
457    if result.created {
458        println!("initialized {app} workspace in {}", result.root.display());
459    } else {
460        println!(
461            "{} already exists (workspace {})",
462            result.root.display(),
463            result.workspace_id
464        );
465    }
466    println!("the {app} server now serves {}", result.root.display());
467
468    if sync {
469        enable_sync(&client).await?;
470    }
471    Ok(0)
472}
473
474/// Turn sync on for the server's workspace over `client`, and print what it syncs as.
475///
476/// The one path behind `init --sync`, `select --sync` and `sync enable`: the server's
477/// `sync.enable`, then its status, printed after, so an unjoined host's "no workgroup knows
478/// it yet" is plain.
479async fn enable_sync(client: &sapphire_ipc::Client) -> Result<()> {
480    let enabled: proto::SyncEnableResult = client
481        .call(proto::SYNC_ENABLE, serde_json::json!({}))
482        .await?;
483    // Never fails on account of the bridge: the workspace is synced either way, and the
484    // status is the user's word for what the workgroup does not know yet.
485    let status: proto::SyncStatusResult = client
486        .call(proto::SYNC_STATUS, serde_json::json!({}))
487        .await
488        .unwrap_or(proto::SyncStatusResult {
489            enabled: true,
490            workspace_id: Some(enabled.workspace_id),
491            ..proto::SyncStatusResult::not_synced()
492        });
493    println!(
494        "syncing as {} ({} peer{})",
495        enabled.workspace_id,
496        status.peers,
497        if status.peers == 1 { "" } else { "s" }
498    );
499    Ok(())
500}
501
502/// `workspace sync …`: the server's workspace's sync, switched after the fact.
503async fn workspace_sync(
504    app: &'static str,
505    version: &'static str,
506    command: WorkspaceSyncCommand,
507) -> Result<i32> {
508    let Some(client) = connect_app(app, version).await? else {
509        return Ok(1);
510    };
511    match command {
512        WorkspaceSyncCommand::Enable => enable_sync(&client).await?,
513        WorkspaceSyncCommand::Disable => {
514            let _: proto::Ack = client
515                .call(proto::SYNC_DISABLE, serde_json::json!({}))
516                .await?;
517            println!("sync is off for the {app} workspace on this host; it keeps its sync id");
518        }
519        WorkspaceSyncCommand::Status => {
520            let status: proto::SyncStatusResult = client
521                .call(proto::SYNC_STATUS, serde_json::json!({}))
522                .await?;
523            for line in describe_sync(&status) {
524                println!("{line}");
525            }
526        }
527    }
528    Ok(0)
529}
530
531/// `workspace sync status`, line by line.
532fn describe_sync(status: &proto::SyncStatusResult) -> Vec<String> {
533    let mut lines = vec![format!(
534        "sync: {}",
535        if status.enabled { "on" } else { "off" }
536    )];
537    if let Some(id) = status.workspace_id {
538        lines.push(format!("workspace id: {id}"));
539    }
540    if status.enabled {
541        lines.push(format!(
542            "peers: {}{}",
543            status.peers,
544            if matches!(status.topology, proto::Topology::Star { .. }) {
545                " (star)"
546            } else {
547                ""
548            }
549        ));
550        lines.push(format!(
551            "bridge: {}",
552            if status.bridge_available {
553                "reachable"
554            } else {
555                "not reachable"
556            }
557        ));
558    }
559    if let Some(paused) = &status.paused {
560        lines.push(format!("paused: {paused}"));
561    }
562    if let Some(error) = &status.last_error {
563        lines.push(format!("last error: {error}"));
564    }
565    lines
566}
567
568/// Render the server's workspace as the CLI prints it: `root state`.
569///
570/// Public so the integration tests can capture it; `workspace show` writes it to standard
571/// output.
572pub async fn render_workspace(client: &sapphire_ipc::Client, out: &mut String) -> Result<i32> {
573    let current: proto::WorkspaceCurrentResult = client
574        .call(proto::WORKSPACE_CURRENT, serde_json::json!({}))
575        .await?;
576    let Some(ws) = current.workspace else {
577        writeln!(
578            out,
579            "no workspace yet; run `workspace init <dir>` or `workspace select <dir>`"
580        )
581        .expect("writing to a String cannot fail");
582        return Ok(1);
583    };
584    writeln!(out, "{} {}", ws.root.display(), describe_state(&ws))
585        .expect("writing to a String cannot fail");
586    Ok(0)
587}
588
589/// `synced (star), embedding 3 pending` and the like.
590fn describe_state(ws: &proto::CurrentWorkspace) -> String {
591    let state = if !ws.reachable {
592        "unreachable"
593    } else if ws.sync.enabled {
594        "synced"
595    } else {
596        "not synced"
597    };
598    let star = if matches!(ws.sync.topology, proto::Topology::Star { .. }) {
599        " (star)"
600    } else {
601        ""
602    };
603    let pending = match &ws.sync.embedding {
604        Some(e) if e.pending > 0 => format!(", embedding {} pending", e.pending),
605        _ => String::new(),
606    };
607    format!("{state}{star}{pending}")
608}
609
610/// Where a workspace command acts: `dir` made absolute against this process's cwd — the
611/// server's cwd is not the user's — or, when the user named none, the app's default
612/// workspace (`<data dir>/workspaces/default`). The cwd is no default: the server is
613/// resident and serves one workspace, so where the command happens to run says nothing
614/// about which one is meant.
615fn workspace_dir(app: &str, dir: Option<PathBuf>) -> std::io::Result<PathBuf> {
616    Ok(match dir {
617        Some(dir) => std::env::current_dir()?.join(dir),
618        None => sapphire_workspace::default_workspace_dir(app),
619    })
620}
621
622/// Connect to `app`'s server, or say none is running.
623async fn connect_app(app: &str, version: &str) -> Result<Option<sapphire_ipc::Client>> {
624    let client = try_connect_app(app, version).await?;
625    if client.is_none() {
626        println!("no {app} server is running");
627    }
628    Ok(client)
629}
630
631/// Connect to `app`'s server; `None`, silently, when none is running.
632async fn try_connect_app(app: &str, version: &str) -> Result<Option<sapphire_ipc::Client>> {
633    let endpoint = Endpoint::for_app(app)?;
634    let client_info = ClientInfo {
635        kind: "cli".to_owned(),
636        version: version.to_owned(),
637        api: proto::API_VERSION,
638        app_api: None,
639        pid: std::process::id(),
640    };
641    let client = sapphire_ipc::connect_or_absent(&endpoint, app, client_info).await?;
642    Ok(client.map(|(c, _)| c))
643}
644
645/// `workspace select`: switch the server to an existing workspace, syncing it with `--sync`.
646async fn workspace_select(
647    app: &'static str,
648    version: &'static str,
649    dir: Option<PathBuf>,
650    sync: bool,
651) -> Result<i32> {
652    let Some(client) = connect_app(app, version).await? else {
653        return Ok(1);
654    };
655    let dir = workspace_dir(app, dir)?;
656    let ws: proto::CurrentWorkspace = client
657        .call(
658            proto::WORKSPACE_SELECT,
659            proto::WorkspaceSelectParams { dir },
660        )
661        .await?;
662    println!("{} {}", ws.root.display(), describe_state(&ws));
663    // A workspace that has synced before is synced again by the select itself.
664    if sync && !ws.sync.enabled {
665        enable_sync(&client).await?;
666    }
667    Ok(0)
668}
669
670/// `workspace move`: move the server's workspace folder.
671async fn workspace_move(app: &'static str, version: &'static str, dir: PathBuf) -> Result<i32> {
672    let Some(client) = connect_app(app, version).await? else {
673        return Ok(1);
674    };
675    // Resolved here: the server's cwd is not the user's.
676    let dir = std::env::current_dir()?.join(dir);
677    let ws: proto::CurrentWorkspace = client
678        .call(proto::WORKSPACE_MOVE, proto::WorkspaceMoveParams { dir })
679        .await?;
680    println!("{} {}", ws.root.display(), describe_state(&ws));
681    Ok(0)
682}
683
684/// `workspace remove`: let go of the server's workspace, deleting it with `--delete`.
685async fn workspace_remove(app: &'static str, version: &'static str, delete: bool) -> Result<i32> {
686    let Some(client) = connect_app(app, version).await? else {
687        return Ok(1);
688    };
689    let _: proto::Ack = client
690        .call(
691            proto::WORKSPACE_REMOVE,
692            proto::WorkspaceRemoveParams { delete },
693        )
694        .await?;
695    println!(
696        "{}",
697        if delete {
698            "removed and deleted"
699        } else {
700            "removed; the files stay"
701        }
702    );
703    Ok(0)
704}
705
706/// `workspace show`: the server's workspace, then the workgroup's workspaces of this app.
707///
708/// The workgroup's ledger is the bridge's to answer, and the bridge being down is not the
709/// server half's failure: the ledger's absence is one line, and the exit is the server
710/// half's.
711async fn workspace_show(app: &'static str, version: &'static str) -> Result<i32> {
712    let Some(client) = connect_app(app, version).await? else {
713        return Ok(1);
714    };
715    let mut out = String::new();
716    let code = render_workspace_show(Arc::new(client), app, &mut out).await?;
717    for line in out.lines() {
718        println!("{line}");
719    }
720    Ok(code)
721}
722
723/// [`workspace_show`]'s text, over one connection to the app's server.
724///
725/// The workgroup half goes through the same connection, relayed to the bridge. Public so
726/// the integration tests can capture it.
727#[doc(hidden)]
728pub async fn render_workspace_show(
729    client: Arc<sapphire_ipc::Client>,
730    app: &str,
731    out: &mut String,
732) -> Result<i32> {
733    let code = render_workspace(&client, out).await?;
734    let bridge = BridgeClient::relayed(client, sapphire_ipc::runtime_dir()?);
735    let workspaces = match bridge.workspaces().await {
736        Ok(workspaces) => workspaces,
737        Err(sapphire_ipc::Error::NotRunning(_)) => {
738            writeln!(out, "no sapphire-bridge is running")
739                .expect("writing to a String cannot fail");
740            return Ok(code);
741        }
742        Err(error) => return Err(error.into()),
743    };
744    let mine: Vec<_> = workspaces
745        .workspaces
746        .into_iter()
747        .filter(|w| w.app_name == app)
748        .collect();
749    if !mine.is_empty() {
750        writeln!(out).expect("writing to a String cannot fail");
751        writeln!(out, "in the workgroup:").expect("writing to a String cannot fail");
752        for workspace in mine {
753            writeln!(out, "{} {}", workspace.name, workspace.workspace_id)
754                .expect("writing to a String cannot fail");
755        }
756    }
757    Ok(code)
758}
759
760/// Probe, handshake and call `SERVER_INFO` in one go, or report absence.
761///
762/// Every step the CLI needs — liveness and the API gate — is inside
763/// [`connect_or_absent`], so the command is that call plus one `SERVER_INFO` round trip.
764/// The API gate doubles as the liveness check here: a live server of another API version
765/// is `ApiVersionMismatch`, which names both API versions and advises upgrading and
766/// restarting the service. The report goes through [`run_status_into`] so tests can
767/// capture it.
768async fn run_status(endpoint: &Endpoint, app: &str, version: &str) -> Result<i32> {
769    let mut out = String::new();
770    let code = run_status_into(endpoint, app, version, &mut out).await?;
771    for line in out.lines() {
772        println!("{line}");
773    }
774    Ok(code)
775}
776
777/// [`run_status`], writing the rendered lines into `out` instead of the process's
778/// standard output.
779async fn run_status_into(
780    endpoint: &Endpoint,
781    app: &str,
782    version: &str,
783    out: &mut String,
784) -> Result<i32> {
785    let client_info = ClientInfo {
786        kind: "cli".to_owned(),
787        version: version.to_owned(),
788        api: proto::API_VERSION,
789        app_api: None,
790        pid: std::process::id(),
791    };
792    let Some((client, _)) = sapphire_ipc::connect_or_absent(endpoint, app, client_info).await?
793    else {
794        // Nothing is listening: the framework's half is only the one line, and the
795        // application's rows are skipped (there is no server to have configured them).
796        writeln!(out, "no {app} server is running").expect("writing to a String cannot fail");
797        return Ok(1);
798    };
799    let report: StatusReport = client
800        .call(
801            sapphire_backend::protocol::SERVER_INFO,
802            serde_json::json!({}),
803        )
804        .await?;
805    writeln!(out, "running: {}", report.running).expect("writing to a String cannot fail");
806    if let Some(version) = &report.version {
807        writeln!(out, "version: {version}").expect("writing to a String cannot fail");
808    }
809    if let Some(pid) = report.pid {
810        writeln!(out, "pid: {pid}").expect("writing to a String cannot fail");
811    }
812    if let Some(managed_by) = &report.managed_by {
813        writeln!(out, "managed_by: {managed_by:?}").expect("writing to a String cannot fail");
814    }
815    for row in &report.app {
816        writeln!(out, "{}: {}", row.name, row.value).expect("writing to a String cannot fail");
817    }
818    // A server older than `server.update` answers method-not-found: there is nothing to
819    // say about releases then, and the restart line still stands.
820    let update: Option<proto::UpdateStatus> = client
821        .call(proto::SERVER_UPDATE, serde_json::json!({}))
822        .await
823        .ok();
824    for line in describe_update(app, version, report.version.as_deref(), update.as_ref()) {
825        writeln!(out, "{line}").expect("writing to a String cannot fail");
826    }
827    Ok(0)
828}
829
830/// The `update` and `restart` lines of `status`.
831///
832/// `installed` is this CLI's version — the executable on disk — and `running` the
833/// server's. A server older than what is installed was upgraded under it and needs a
834/// restart; a release newer than what is installed is an update to install. A release
835/// that is newer than the server but already installed is only the restart.
836fn describe_update(
837    app: &str,
838    installed: &str,
839    running: Option<&str>,
840    update: Option<&proto::UpdateStatus>,
841) -> Vec<String> {
842    let parse = |v: &str| semver::Version::parse(v).ok();
843    let installed_v = parse(installed);
844    let mut lines = Vec::new();
845    if let Some(update) = update.filter(|u| u.enabled) {
846        match (&update.latest, &update.last_error) {
847            (Some(latest), _) => {
848                let newer = match (parse(&latest.version), &installed_v) {
849                    (Some(latest), Some(installed)) => latest > *installed,
850                    _ => update.update_available,
851                };
852                if newer {
853                    lines.push(format!(
854                        "update: {} is available ({})",
855                        latest.version, latest.url
856                    ));
857                } else {
858                    lines.push(format!(
859                        "update: up to date (latest release {})",
860                        latest.version
861                    ));
862                }
863            }
864            (None, Some(error)) => lines.push(format!("update: could not check: {error}")),
865            (None, None) => lines.push("update: not checked yet".to_owned()),
866        }
867    }
868    if let (Some(running), Some(installed)) = (running.and_then(parse), installed_v)
869        && installed > running
870    {
871        lines.push(format!(
872            "restart: needed: {installed} is installed but {running} is running; restart the {app} service"
873        ));
874    }
875    lines
876}
877#[cfg(test)]
878mod tests {
879    use super::*;
880    use clap::Parser;
881
882    /// The composition every app binary uses: an app-owned subcommand enum whose framework
883    /// verbs ride in on a flattened variant (spec decision 2).
884    ///
885    /// clap 4 rejects `#[command(flatten)]` on a struct field beside a
886    /// `#[command(subcommand)]` field — two subcommand enums cannot share one level, and a
887    /// flattened field must implement `clap::Args`, which the `Subcommand` derive does not
888    /// provide. The plan's Risks section names this probe as the decision, and the flat
889    /// fallback is what it decided: one subcommand enum, every verb at the top level.
890    #[derive(Parser)]
891    struct Probe {
892        #[command(subcommand)]
893        command: Command,
894    }
895
896    #[derive(Debug, clap::Subcommand)]
897    enum Command {
898        /// An app-specific verb that must parse beside the framework's.
899        Greet,
900        #[command(flatten)]
901        Framework(FrameworkCommand),
902    }
903
904    /// A desktop binary: the same verbs, and none at all to open the window.
905    #[derive(Parser)]
906    struct DesktopProbe {
907        #[command(subcommand)]
908        command: Option<Command>,
909    }
910
911    #[test]
912    fn a_desktop_binary_takes_the_same_verbs_or_none() {
913        let probe = DesktopProbe::try_parse_from(["app"]).unwrap();
914        assert!(probe.command.is_none());
915        let probe = DesktopProbe::try_parse_from(["app", "serve"]).unwrap();
916        assert!(matches!(
917            probe.command,
918            Some(Command::Framework(FrameworkCommand::Serve))
919        ));
920        let probe = DesktopProbe::try_parse_from(["app", "greet"]).unwrap();
921        assert!(matches!(probe.command, Some(Command::Greet)));
922        // The CLI version's bare invocation is an error, which clap answers with the help.
923        assert!(Probe::try_parse_from(["app"]).is_err());
924    }
925
926    #[test]
927    fn app_and_framework_commands_parse_side_by_side() {
928        let probe = Probe::try_parse_from(["app", "greet"]).unwrap();
929        assert!(matches!(probe.command, Command::Greet));
930        let probe = Probe::try_parse_from(["app", "serve"]).unwrap();
931        assert!(matches!(
932            probe.command,
933            Command::Framework(FrameworkCommand::Serve)
934        ));
935        let probe = Probe::try_parse_from(["app", "status"]).unwrap();
936        assert!(matches!(
937            probe.command,
938            Command::Framework(FrameworkCommand::Status)
939        ));
940    }
941
942    #[cfg(feature = "mcp")]
943    #[test]
944    fn the_mcp_command_parses_beside_the_apps() {
945        let probe = Probe::try_parse_from(["app", "mcp"]).unwrap();
946        assert!(matches!(
947            probe.command,
948            Command::Framework(FrameworkCommand::Mcp)
949        ));
950    }
951
952    #[test]
953    fn the_update_command_parses_with_and_without_the_bridge() {
954        let probe = Probe::try_parse_from(["app", "update", "--check", "-y"]).unwrap();
955        let Command::Framework(FrameworkCommand::Update(args)) = probe.command else {
956            panic!("not update");
957        };
958        assert!(args.update.check && args.update.yes && !args.no_bridge);
959        let probe = Probe::try_parse_from(["app", "update", "--no-bridge"]).unwrap();
960        let Command::Framework(FrameworkCommand::Update(args)) = probe.command else {
961            panic!("not update");
962        };
963        assert!(args.no_bridge);
964    }
965
966    #[test]
967    fn the_bridge_is_found_in_the_first_directory_of_path_that_has_it() {
968        let tmp = tempfile::tempdir().unwrap();
969        let (empty, first, second) = (
970            tmp.path().join("empty"),
971            tmp.path().join("first"),
972            tmp.path().join("second"),
973        );
974        let file = format!("sapphire-bridge{}", std::env::consts::EXE_SUFFIX);
975        for dir in [&empty, &first, &second] {
976            std::fs::create_dir(dir).unwrap();
977        }
978        std::fs::write(first.join(&file), b"").unwrap();
979        std::fs::write(second.join(&file), b"").unwrap();
980        let path = std::env::join_paths([&empty, &first, &second]).unwrap();
981        assert_eq!(
982            find_on_path("sapphire-bridge", Some(&path)),
983            Some(first.join(&file))
984        );
985        let path = std::env::join_paths([&empty]).unwrap();
986        assert_eq!(find_on_path("sapphire-bridge", Some(&path)), None);
987        assert_eq!(find_on_path("sapphire-bridge", None), None);
988    }
989
990    /// An executable shell script at `dir/name` that runs `body`.
991    #[cfg(unix)]
992    fn script(dir: &std::path::Path, name: &str, body: &str) -> PathBuf {
993        use std::os::unix::fs::PermissionsExt;
994        let path = dir.join(name);
995        std::fs::write(&path, format!("#!/bin/sh\n{body}\n")).unwrap();
996        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
997        path
998    }
999
1000    #[cfg(unix)]
1001    #[tokio::test]
1002    async fn the_bridge_runs_its_own_update_with_the_apps_flags() {
1003        let tmp = tempfile::tempdir().unwrap();
1004        let log = tmp.path().join("args");
1005        // Records the real run (not the `--help` probe) and exits as an update that
1006        // declined would.
1007        let exe = script(
1008            tmp.path(),
1009            "bridge",
1010            &format!(
1011                r#"case "$*" in *--help*) exit 0;; esac; echo "$@" > {}; exit 1"#,
1012                log.display()
1013            ),
1014        );
1015        let args = sapphire_framework_update::UpdateArgs {
1016            check: true,
1017            yes: true,
1018        };
1019        assert_eq!(run_bridge_update(&exe, &args).await.unwrap(), 1);
1020        assert_eq!(
1021            std::fs::read_to_string(&log).unwrap().trim(),
1022            "update --check --yes"
1023        );
1024    }
1025
1026    #[cfg(unix)]
1027    #[tokio::test]
1028    async fn a_bridge_without_update_is_not_run() {
1029        let tmp = tempfile::tempdir().unwrap();
1030        let runs = tmp.path().join("runs");
1031        // What clap does with an unknown subcommand: exit 2, whatever the arguments.
1032        let exe = script(
1033            tmp.path(),
1034            "bridge",
1035            &format!(r#"echo "$*" >> {}; exit 2"#, runs.display()),
1036        );
1037        let code = run_bridge_update(&exe, &Default::default()).await.unwrap();
1038        assert_eq!(code, 1);
1039        assert_eq!(
1040            std::fs::read_to_string(&runs).unwrap(),
1041            "update --help\n",
1042            "only the probe ran"
1043        );
1044    }
1045
1046    #[test]
1047    fn the_service_subcommands_parse() {
1048        for args in [
1049            vec!["app", "service", "install"],
1050            vec!["app", "service", "uninstall"],
1051            vec!["app", "service", "status"],
1052        ] {
1053            assert!(Probe::try_parse_from(&args).is_ok(), "{args:?}");
1054        }
1055    }
1056
1057    #[test]
1058    fn the_workspace_commands_parse() {
1059        for args in [
1060            vec!["app", "workspace", "init"],
1061            vec!["app", "workspace", "init", "papers"],
1062            vec!["app", "workspace", "init", "--sync"],
1063            vec!["app", "workspace", "show"],
1064            vec!["app", "workspace", "select", "papers"],
1065            vec!["app", "workspace", "select", "--sync"],
1066            vec!["app", "workspace", "select", "papers", "--sync"],
1067            vec!["app", "workspace", "sync", "enable"],
1068            vec!["app", "workspace", "sync", "disable"],
1069            vec!["app", "workspace", "sync", "status"],
1070            vec![
1071                "app",
1072                "workspace",
1073                "init",
1074                "--sync",
1075                "--remote-workspace=Ledger",
1076            ],
1077            vec![
1078                "app",
1079                "workspace",
1080                "init",
1081                "papers",
1082                "--sync",
1083                "--remote-workspace",
1084                "Ledger",
1085            ],
1086            vec!["app", "workspace", "move", "../papers"],
1087            vec!["app", "workspace", "remove"],
1088            vec!["app", "workspace", "remove", "--delete"],
1089        ] {
1090            assert!(Probe::try_parse_from(&args).is_ok(), "{args:?}");
1091        }
1092    }
1093
1094    #[test]
1095    fn a_remote_workspace_needs_sync() {
1096        let args = ["app", "workspace", "init", "--remote-workspace=Ledger"];
1097        assert!(Probe::try_parse_from(args).is_err());
1098    }
1099
1100    #[test]
1101    fn bare_invocation_prints_the_help() {
1102        // <app> with no subcommand prints the help; the server starts only on an explicit
1103        // `serve`. An app CLI gets that by a required subcommand and
1104        // `arg_required_else_help`, as this probe does.
1105        #[derive(Parser)]
1106        #[command(arg_required_else_help = true)]
1107        struct Bare {
1108            #[command(subcommand)]
1109            command: Command,
1110        }
1111        let err = Bare::try_parse_from(["app"]).err().unwrap();
1112        assert_eq!(
1113            err.kind(),
1114            clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
1115        );
1116    }
1117}
1118
1119#[cfg(test)]
1120mod status_tests {
1121    use super::*;
1122    use sapphire_workspace::AppContext;
1123
1124    static CTX: AppContext = AppContext::new("sapphire-statustest");
1125
1126    /// Wait until something is listening on `endpoint`.
1127    ///
1128    /// `tokio::spawn(server.run())` only schedules the server; without this wait a fast
1129    /// `run_status` probe can run before `run` has bound the socket, and with nothing
1130    /// listening that single unlucky probe is the whole test failing.
1131    async fn wait_until_listening(endpoint: &Endpoint) {
1132        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);
1133        while !sapphire_ipc::probe(endpoint).await.unwrap() {
1134            assert!(
1135                tokio::time::Instant::now() < deadline,
1136                "the server never started listening"
1137            );
1138            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
1139        }
1140    }
1141
1142    #[tokio::test]
1143    async fn status_reports_no_server_when_none_is_running() {
1144        let tmp = tempfile::tempdir().unwrap();
1145        let endpoint = sapphire_ipc::Endpoint::in_dir("status-test", tmp.path().to_path_buf());
1146        let code = run_status(&endpoint, "status-test", "0.0.0").await.unwrap();
1147        assert_eq!(code, 1, "no server is a non-zero exit");
1148    }
1149
1150    fn update(latest: Option<&str>, error: Option<&str>) -> proto::UpdateStatus {
1151        proto::UpdateStatus {
1152            enabled: true,
1153            latest: latest.map(|version| proto::ReleaseInfo {
1154                version: version.to_owned(),
1155                url: format!("https://example.invalid/v{version}"),
1156            }),
1157            update_available: false,
1158            last_error: error.map(str::to_owned),
1159        }
1160    }
1161
1162    #[test]
1163    fn status_names_a_newer_release_and_nothing_when_up_to_date() {
1164        let lines = describe_update(
1165            "app",
1166            "0.19.0",
1167            Some("0.19.0"),
1168            Some(&update(Some("0.20.0"), None)),
1169        );
1170        assert_eq!(
1171            lines,
1172            vec!["update: 0.20.0 is available (https://example.invalid/v0.20.0)"]
1173        );
1174        let lines = describe_update(
1175            "app",
1176            "0.19.0",
1177            Some("0.19.0"),
1178            Some(&update(Some("0.19.0"), None)),
1179        );
1180        assert_eq!(lines, vec!["update: up to date (latest release 0.19.0)"]);
1181    }
1182
1183    #[test]
1184    fn status_asks_for_a_restart_when_the_installed_server_is_newer_than_the_running_one() {
1185        // Installed 0.20.0 under a running 0.19.0: the release is no longer news, the
1186        // restart is.
1187        let lines = describe_update(
1188            "app",
1189            "0.20.0",
1190            Some("0.19.0"),
1191            Some(&update(Some("0.20.0"), None)),
1192        );
1193        assert_eq!(
1194            lines,
1195            vec![
1196                "update: up to date (latest release 0.20.0)",
1197                "restart: needed: 0.20.0 is installed but 0.19.0 is running; restart the app service",
1198            ]
1199        );
1200        // An older server without `server.update` still gets the restart line.
1201        let lines = describe_update("app", "0.20.0", Some("0.19.0"), None);
1202        assert_eq!(lines.len(), 1);
1203        assert!(lines[0].starts_with("restart: needed"));
1204    }
1205
1206    #[test]
1207    fn status_says_why_a_check_failed_and_nothing_when_checks_are_off() {
1208        let lines = describe_update(
1209            "app",
1210            "0.19.0",
1211            Some("0.19.0"),
1212            Some(&update(None, Some("offline"))),
1213        );
1214        assert_eq!(lines, vec!["update: could not check: offline"]);
1215        let off = proto::UpdateStatus::default();
1216        assert!(describe_update("app", "0.19.0", Some("0.19.0"), Some(&off)).is_empty());
1217    }
1218
1219    #[test]
1220    fn an_app_s_releases_are_checked_with_the_organization_s_key_unless_it_names_one() {
1221        let key = |source: crate::ReleaseSource| {
1222            AppServer::new(&CTX, "0.19.0")
1223                .releases(source)
1224                .release_source()
1225                .and_then(|s| s.update_pubkey().map(str::to_owned))
1226        };
1227        assert_eq!(
1228            key(crate::ReleaseSource::github("o", "r")).as_deref(),
1229            Some(sapphire_framework_update::UPDATE_PUBKEY)
1230        );
1231        assert_eq!(
1232            key(crate::ReleaseSource::github("o", "r").pubkey("own")).as_deref(),
1233            Some("own")
1234        );
1235    }
1236
1237    #[tokio::test(flavor = "multi_thread")]
1238    async fn status_shows_a_newer_release_the_server_found() {
1239        let tmp = tempfile::tempdir().unwrap();
1240        let endpoint = sapphire_ipc::Endpoint::in_dir("status-test", tmp.path().to_path_buf());
1241        let api = crate::update::stub::one_response(
1242            "200 OK",
1243            r#"[{"tag_name":"v0.20.0","html_url":"https://example.invalid/v0.20.0"}]"#,
1244        )
1245        .await;
1246        let server = AppServer::new(&CTX, "0.19.0")
1247            .endpoint(endpoint.clone())
1248            .selection_file(tmp.path().join("workspace.toml"))
1249            .releases(crate::ReleaseSource::github("o", "r").api_base(api));
1250        let handle = tokio::spawn(async move { server.run().await });
1251        wait_until_listening(&endpoint).await;
1252
1253        // The first look runs as the server starts; wait for its answer to land.
1254        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(10);
1255        let out = loop {
1256            let mut out = String::new();
1257            run_status_into(&endpoint, CTX.app_name, "0.19.0", &mut out)
1258                .await
1259                .unwrap();
1260            if !out.contains("not checked yet") {
1261                break out;
1262            }
1263            assert!(
1264                tokio::time::Instant::now() < deadline,
1265                "never checked: {out}"
1266            );
1267            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
1268        };
1269        assert!(
1270            out.contains("update: 0.20.0 is available (https://example.invalid/v0.20.0)"),
1271            "output was: {out}"
1272        );
1273        assert!(!out.contains("restart:"), "output was: {out}");
1274
1275        let (client, _) = sapphire_ipc::connect_or_absent(
1276            &endpoint,
1277            CTX.app_name,
1278            sapphire_ipc::ClientInfo {
1279                kind: "test".into(),
1280                version: "0.19.0".into(),
1281                api: sapphire_backend::protocol::API_VERSION,
1282                app_api: None,
1283                pid: std::process::id(),
1284            },
1285        )
1286        .await
1287        .unwrap()
1288        .expect("the server is listening");
1289        let _: serde_json::Value = client
1290            .call(sapphire_ipc::SHUTDOWN_METHOD, serde_json::json!({}))
1291            .await
1292            .unwrap();
1293        handle.await.unwrap().unwrap();
1294    }
1295
1296    #[tokio::test(flavor = "multi_thread")]
1297    async fn status_shows_the_extension_rows_of_a_running_server() {
1298        let tmp = tempfile::tempdir().unwrap();
1299        let endpoint = sapphire_ipc::Endpoint::in_dir("status-test", tmp.path().to_path_buf());
1300        let server = AppServer::new(&CTX, "0.0.0")
1301            .endpoint(endpoint.clone())
1302            // This context's directories are never initialised here.
1303            .selection_file(tmp.path().join("workspace.toml"))
1304            .status_rows(std::sync::Arc::new(|| {
1305                vec![StatusRow {
1306                    name: "sync".into(),
1307                    value: "on".into(),
1308                }]
1309            }));
1310        let handle = tokio::spawn(async move { server.run().await });
1311        wait_until_listening(&endpoint).await;
1312
1313        // The report goes through the sink face so the rendering is asserted, not just
1314        // the exit code.
1315        let mut out = String::new();
1316        let code = run_status_into(&endpoint, CTX.app_name, "0.0.0", &mut out)
1317            .await
1318            .unwrap();
1319        assert_eq!(code, 0);
1320        assert!(out.contains("running: true"), "output was: {out}");
1321        assert!(out.contains("sync: on"), "output was: {out}");
1322
1323        let (client, _) = sapphire_ipc::connect_or_absent(
1324            &endpoint,
1325            CTX.app_name,
1326            sapphire_ipc::ClientInfo {
1327                kind: "test".into(),
1328                version: "0.0.0".into(),
1329                api: sapphire_backend::protocol::API_VERSION,
1330                app_api: None,
1331                pid: std::process::id(),
1332            },
1333        )
1334        .await
1335        .unwrap()
1336        .expect("the server is listening");
1337        let _: serde_json::Value = client
1338            .call(sapphire_ipc::SHUTDOWN_METHOD, serde_json::json!({}))
1339            .await
1340            .unwrap();
1341        handle.await.unwrap().unwrap();
1342    }
1343}
1344
1345#[cfg(test)]
1346mod service_spec_tests {
1347    use super::*;
1348    use sapphire_workspace::AppContext;
1349
1350    static CTX: AppContext = AppContext::new("sapphire-servicetest");
1351
1352    #[test]
1353    fn the_generated_spec_runs_the_server_not_the_cli() {
1354        // A service manager starts the executable directly, and the executable's bare
1355        // invocation is `serve`: the unit's argv must be exactly that, so the server that
1356        // starts has no CLI verbs on its command line to misparse.
1357        let spec = AppServer::new(&CTX, "0.0.0").service_spec();
1358        assert_eq!(spec.args, vec!["serve".to_owned()]);
1359    }
1360
1361    #[test]
1362    fn the_generated_spec_retires_the_first_label() {
1363        // The first label sapphire registered on macOS; corundum retires its own earlier
1364        // one (net.sapphire-turtle.<app>) by itself.
1365        let spec = AppServer::new(&CTX, "0.0.0").service_spec();
1366        assert_eq!(
1367            spec.legacy_labels,
1368            [format!("net.fireturtle.sapphire.{}", CTX.app_name)]
1369        );
1370    }
1371
1372    #[test]
1373    fn the_generated_spec_names_this_application() {
1374        let spec = AppServer::new(&CTX, "0.0.0").service_spec();
1375        assert_eq!(spec.app_name, CTX.app_name);
1376    }
1377
1378    #[test]
1379    fn the_generated_spec_describes_the_server() {
1380        let spec = AppServer::new(&CTX, "0.0.0").service_spec();
1381        assert!(
1382            spec.description.contains(CTX.app_name),
1383            "the unit's description should name the application: {:?}",
1384            spec.description
1385        );
1386        assert!(spec.description.contains("0.0.0"));
1387    }
1388}