feat(board): run shared session programs

Author: ZR233

README.md

@@ -317,12 +317,31 @@ ostool board config
 `server` 应使用包含 `http://` 或 `https://` 的完整 URL；可选的 `port` 会覆盖 URL 中的端口。为兼容旧的局域网配置，裸 IPv4 或 IPv6 地址会自动补为 `http://`。基线版本写出的 `server_ip` / `port` 也会在读取时迁移为 `server` / `port`，下一次保存配置时只写新格式；无 scheme 的主机名不支持。项目级 `.board.toml` 中的 `server` / `port` 仍可用于 `ostool board run`，其优先级低于命令行参数，高于全局配置。
 
 `.board.toml` 可以用 `session_files` 声明相对于配置文件目录的共享文件。调用方通过
-`BoardRunRequest::with_session_files` 提供该目录，ostool 会在 board session
+`BoardRunRequest::with_session_root` 提供该目录，ostool 会在 board session
 建立后按原相对路径上传，并在 `shell_init_cmd` 中展开
 `${boardServerIp}`、`${boardServerHttpBaseUrl}` 和
 `${sessionFile:<relative-path>}`。绝对路径、`..`、符号链接逃逸、重复路径及缺失
 文件都会在运行前被拒绝；接口不提供 alias 或上传改名。
 
+只需运行一个共享程序时，可改用声明式配置：
+
+```toml
+board_type = "AKA-00-SG2002"
+shell_prefix = "root@starry:"
+success_regex = ["(?m)^PROGRAM_OK\\s*$"]
+
+[session_program]
+path = "bin/probe"
+args = ["--server", "${boardServerIp}"]
+```
+
+`session_program.path` 会自动加入共享文件，无需同时写入 `session_files`。检测到 shell
+prompt 后，ostool 在 `/tmp/ostool-session/<session_id>/` 下按原相对路径下载所有
+session 文件，为程序添加执行权限，并以经过 POSIX shell 引号保护的 argv 运行程序。
+下载会在 60 秒内依次尝试 curl 和 wget；下载、赋权或程序退出失败都会触发 board
+测试失败并进入正常的 session release 流程。`session_program` 与
+`shell_init_cmd` 互斥。
+
 ### 公网开发板认证
 
 局域网直接连接 `ostool-server` 时保留上述匿名 HTTP 配置。公网认证网关使用完整 HTTPS 地址：

ostool/src/board/config.rs

@@ -10,6 +10,17 @@ use crate::{
     run::shell_init::normalize_shell_init_config,
 };
 
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct BoardSessionProgram {
+    /// Program path relative to the board configuration's session root.
+    pub path: PathBuf,
+    /// Literal argv entries. Project and board-session placeholders are expanded
+    /// before each entry is POSIX-shell quoted.
+    #[serde(default)]
+    pub args: Vec<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, Default, PartialEq, Eq)]
 #[serde(deny_unknown_fields)]
 pub struct BoardRunConfig {
@@ -20,6 +31,9 @@ pub struct BoardRunConfig {
     /// relative path on the session HTTP endpoint.
     #[serde(default)]
     pub session_files: Vec<PathBuf>,
+    /// Program uploaded, downloaded, and executed for this board session.
+    #[serde(default)]
+    pub session_program: Option<BoardSessionProgram>,
     pub dtb_file: Option<String>,
     pub kernel_load_addr: Option<String>,
     pub fit_load_addr: Option<String>,
@@ -168,6 +182,13 @@ impl BoardRunConfig {
             .as_deref()
             .map(|value| variables::expand_variables(value, scope))
             .transpose()?;
+        if let Some(program) = self.session_program.as_mut() {
+            program.args = program
+                .args
+                .iter()
+                .map(|value| variables::expand_variables(value, scope))
+                .collect::<anyhow::Result<Vec<_>>>()?;
+        }
         self.server = self
             .server
             .as_deref()
@@ -212,7 +233,34 @@ impl BoardRunConfig {
             &mut self.shell_prefix,
             &mut self.shell_init_cmd,
             config_name,
-        )
+        )?;
+        if let Some(program) = self.session_program.as_ref() {
+            if self.shell_init_cmd.is_some() {
+                anyhow::bail!(
+                    "`session_program` and `shell_init_cmd` are mutually exclusive in {config_name}"
+                );
+            }
+            if self.shell_prefix.is_none() {
+                anyhow::bail!("`session_program` requires `shell_prefix` in {config_name}");
+            }
+            if program.path.as_os_str().is_empty() {
+                anyhow::bail!("`session_program.path` must not be empty in {config_name}");
+            }
+            if program.path.to_string_lossy().contains("${") {
+                anyhow::bail!("`session_program.path` must not contain variables in {config_name}");
+            }
+            if let Some(argument) = program
+                .args
+                .iter()
+                .find(|argument| argument.contains(['\0', '\r', '\n']))
+            {
+                anyhow::bail!(
+                    "`session_program.args` must not contain NUL or newline characters in \
+                     {config_name}: {argument:?}"
+                );
+            }
+        }
+        Ok(())
     }
 }
 
@@ -229,7 +277,7 @@ fn normalize_optional_string(value: &mut Option<String>) {
 
 #[cfg(test)]
 mod tests {
-    use super::BoardRunConfig;
+    use super::{BoardRunConfig, BoardSessionProgram};
     use crate::{
         board::global_config::BoardGlobalConfig,
         board::{ensure_run_config_in_dir, read_run_config_from_path},
@@ -317,6 +365,28 @@ port = 9000
         assert_eq!(decoded, config);
     }
 
+    #[test]
+    fn board_run_config_session_program_toml_round_trip() {
+        let config = BoardRunConfig {
+            board_type: "aka-00-sg2002".to_string(),
+            shell_prefix: Some("root@starry:".to_string()),
+            session_program: Some(BoardSessionProgram {
+                path: PathBuf::from("bin/sg2002-libuvc-init"),
+                args: vec![
+                    "--server".to_string(),
+                    "${boardServerIp}".to_string(),
+                    "argument with spaces".to_string(),
+                ],
+            }),
+            ..Default::default()
+        };
+
+        let encoded = toml::to_string(&config).unwrap();
+        let decoded: BoardRunConfig = toml::from_str(&encoded).unwrap();
+
+        assert_eq!(decoded, config);
+    }
+
     #[test]
     fn legacy_board_run_config_defaults_to_no_session_files() {
         let fixture = LegacyBoardRunConfigFixture {
@@ -327,6 +397,44 @@ port = 9000
         let decoded: BoardRunConfig = toml::from_str(&encoded).unwrap();
 
         assert!(decoded.session_files.is_empty());
+        assert!(decoded.session_program.is_none());
+    }
+
+    #[test]
+    fn session_program_rejects_shell_init_command_and_missing_prefix() {
+        let mut conflicting = BoardRunConfig {
+            board_type: "aka-00-sg2002".to_string(),
+            shell_prefix: Some("root@starry:".to_string()),
+            shell_init_cmd: Some("echo legacy".to_string()),
+            session_program: Some(BoardSessionProgram {
+                path: PathBuf::from("bin/probe"),
+                args: Vec::new(),
+            }),
+            ..Default::default()
+        };
+        assert!(
+            conflicting
+                .normalize("test board config")
+                .unwrap_err()
+                .to_string()
+                .contains("mutually exclusive")
+        );
+
+        let mut missing_prefix = BoardRunConfig {
+            board_type: "aka-00-sg2002".to_string(),
+            session_program: Some(BoardSessionProgram {
+                path: PathBuf::from("bin/probe"),
+                args: Vec::new(),
+            }),
+            ..Default::default()
+        };
+        assert!(
+            missing_prefix
+                .normalize("test board config")
+                .unwrap_err()
+                .to_string()
+                .contains("shell_prefix")
+        );
     }
 
     #[test]

ostool/src/board/mod.rs

@@ -325,9 +325,9 @@ pub async fn run_prepared_board(
     board_config: &BoardRunConfig,
     options: RunBoardOptions,
 ) -> anyhow::Result<()> {
-    if !board_config.session_files.is_empty() {
+    if !board_config.session_files.is_empty() || board_config.session_program.is_some() {
         anyhow::bail!(
-            "board config contains `session_files`; use BoardRunRequest::with_session_files to provide the configuration directory"
+            "board config contains session assets; use BoardRunRequest::with_session_root to provide the session root"
         );
     }
     run_prepared_board_with_request(
@@ -382,6 +382,7 @@ pub async fn run_prepared_board_with_request(
 
 fn board_session_setup_required(board_config: &BoardRunConfig, has_session_files: bool) -> bool {
     has_session_files
+        || board_config.session_program.is_some()
         || board_config
             .shell_init_cmd
             .as_deref()

ostool/src/board/request.rs

@@ -27,11 +27,84 @@ impl BoardRunRequest {
         root: &Path,
         relative_paths: &[PathBuf],
     ) -> anyhow::Result<Self> {
-        self.session_files = collect_session_files(root, relative_paths)?;
+        let mut declared_paths = relative_paths.to_vec();
+        if let Some(program) = self.board_config.session_program.as_ref() {
+            declared_paths.push(program.path.clone());
+        }
+        self.session_files = collect_session_files(root, &declared_paths)?;
+        Ok(self)
+    }
+
+    /// Resolves every file declared by the board configuration under `root`.
+    ///
+    /// This includes both `session_files` and `session_program.path`.
+    pub fn with_session_root(mut self, root: &Path) -> anyhow::Result<Self> {
+        let declared_files = self.board_config.session_files.clone();
+        self = self.with_session_files(root, &declared_files)?;
         Ok(self)
     }
 
     pub(crate) fn into_parts(self) -> (BoardRunConfig, RunBoardOptions, Vec<SessionFileUpload>) {
         (self.board_config, self.options, self.session_files)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::{fs, path::PathBuf};
+
+    use tempfile::tempdir;
+
+    use super::*;
+    use crate::board::config::BoardSessionProgram;
+
+    #[test]
+    fn session_root_collects_declared_files_and_program() {
+        let root = tempdir().unwrap();
+        fs::create_dir_all(root.path().join("bin")).unwrap();
+        fs::write(root.path().join("config.toml"), b"config").unwrap();
+        fs::write(root.path().join("bin/probe"), b"probe").unwrap();
+        let config = BoardRunConfig {
+            board_type: "test-board".into(),
+            session_files: vec![PathBuf::from("config.toml")],
+            session_program: Some(BoardSessionProgram {
+                path: PathBuf::from("bin/probe"),
+                args: Vec::new(),
+            }),
+            ..Default::default()
+        };
+
+        let request = BoardRunRequest::new(config, RunBoardOptions::default())
+            .with_session_root(root.path())
+            .unwrap();
+        let (_, _, uploads) = request.into_parts();
+        let paths = uploads
+            .iter()
+            .map(SessionFileUpload::relative_path)
+            .collect::<Vec<_>>();
+
+        assert_eq!(paths, ["config.toml", "bin/probe"]);
+    }
+
+    #[test]
+    fn session_root_rejects_duplicate_program_path() {
+        let root = tempdir().unwrap();
+        fs::create_dir_all(root.path().join("bin")).unwrap();
+        fs::write(root.path().join("bin/probe"), b"probe").unwrap();
+        let config = BoardRunConfig {
+            board_type: "test-board".into(),
+            session_files: vec![PathBuf::from("bin/probe")],
+            session_program: Some(BoardSessionProgram {
+                path: PathBuf::from("bin/probe"),
+                args: Vec::new(),
+            }),
+            ..Default::default()
+        };
+
+        let error = BoardRunRequest::new(config, RunBoardOptions::default())
+            .with_session_root(root.path())
+            .unwrap_err();
+
+        assert!(error.to_string().contains("duplicate"));
+    }
+}