From 550e66b1e234f3d34cdd72a60a3978dfdb5bd179 Mon Sep 17 00:00:00 2001 From: Marqdo Agent Date: Sat, 21 Nov 2026 08:54:29 +0800 Subject: [PATCH] refactor(cli,host): split command entry points and provider/effects modules --- crates/cli/src/commands.rs | 507 +---------------------- crates/cli/src/commands/check.rs | 68 +++ crates/cli/src/commands/inspect.rs | 132 ++++++ crates/cli/src/commands/run.rs | 306 ++++++++++++++ crates/marqdo-host/src/host.rs | 154 +------ crates/marqdo-host/src/host/effects.rs | 41 ++ crates/marqdo-host/src/host/providers.rs | 127 ++++++ docs/STATUS.md | 12 +- docs/architecture/CURRENT.md | 9 +- docs/evidence/2026-11-21-module-split.md | 23 +- 10 files changed, 708 insertions(+), 671 deletions(-) create mode 100644 crates/cli/src/commands/check.rs create mode 100644 crates/cli/src/commands/inspect.rs create mode 100644 crates/cli/src/commands/run.rs create mode 100644 crates/marqdo-host/src/host/effects.rs create mode 100644 crates/marqdo-host/src/host/providers.rs diff --git a/crates/cli/src/commands.rs b/crates/cli/src/commands.rs index 9546992..01c86a9 100644 --- a/crates/cli/src/commands.rs +++ b/crates/cli/src/commands.rs @@ -9,8 +9,15 @@ use marqdo_sandbox::{PlatformCapabilities, SandboxMode}; use marqdo_span::Span; use serde_json::json; +mod check; +mod inspect; +mod run; mod sandbox; +pub use check::check; +pub use inspect::inspect; +pub use inspect::InspectFlags; +pub use run::execute; pub use sandbox::SandboxSettings; use crate::args; @@ -199,206 +206,6 @@ fn plugin_signature(raw: &str) -> Result, - json: bool, - refs: bool, - plugins: &[PathBuf], - emit: Option<&Path>, -) -> i32 { - let mut project = match load_project(file, json) { - Ok(project) => project, - Err(code) => return code, - }; - if let Err(error) = add_static_plugin_descriptors(&mut project, plugins) { - if json { - output::print_json(&json!({"success": false, "error": error})); - } else { - eprintln!("error: {error}"); - } - return 2; - } - if refs { - let ref_diagnostics = validate_refs(&project); - project.diagnostics.extend(ref_diagnostics); - } - let errors = output::error_count(&project.diagnostics); - if let Some(path) = emit { - if errors > 0 { - let _ = std::fs::remove_file(path); - } else if let Err(error) = crate::analysis::write(&project, path) { - eprintln!("error: {error}"); - return 2; - } - } - if json { - output::print_json(&json!({ - "command": "check", - "success": errors == 0, - "errors": errors, - "diagnostics": output::diagnostics_json(&project.diagnostics), - })); - } else { - let text = output::render_text(&project.diagnostics); - eprint!("{text}"); - if errors == 0 { - let checked = project - .program - .modules - .keys() - .filter(|id| !id.instance.starts_with("std:")) - .count(); - println!("checked {checked} module(s): ok"); - } else { - eprintln!( - "check failed: {} error(s), {} warning(s)", - errors, - project.diagnostics.len() - errors - ); - } - } - if errors == 0 { - 0 - } else { - 1 - } -} - -/// Options for `marqdo inspect`. -#[derive(Debug, Clone, Default)] -pub struct InspectFlags { - /// Show the Markdown AST. - pub ast: bool, - /// Show heading units. - pub units: bool, - /// Show inferred/explicit signatures. - pub signature: bool, - /// Show executable IR. - pub ir: bool, - /// Show link reference edges. - pub refs: bool, - /// Show platform capability report. - pub platform: bool, -} - -/// `marqdo inspect`. -pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 { - let project = match load_project(file, json) { - Ok(project) => project, - Err(code) => return code, - }; - let entry = project.entry_file(); - let module = &entry.analysis.module; - let selected_any = - flags.ast || flags.units || flags.signature || flags.ir || flags.refs || flags.platform; - if json { - let mut object = serde_json::Map::new(); - object.insert("command".into(), json!("inspect")); - object.insert("module".into(), json!(entry.module_id.to_string())); - if !selected_any { - object.insert("summary".into(), summary_json(&project)); - } - if flags.ast { - object.insert( - "ast".into(), - serde_json::to_value(&entry.analysis.document.root).unwrap_or_default(), - ); - } - if flags.units { - object.insert( - "units".into(), - serde_json::to_value(&entry.analysis.units.units).unwrap_or_default(), - ); - } - if flags.signature { - object.insert("signatures".into(), signatures_json(module)); - } - if flags.ir { - object.insert( - "ir".into(), - serde_json::to_value(&module.functions).unwrap_or_default(), - ); - } - if flags.refs { - object.insert("refs".into(), json!(refs_json(&project))); - } - if flags.platform { - object.insert( - "platform".into(), - serde_json::to_value(PlatformCapabilities::detect()).unwrap_or_default(), - ); - } - output::print_json(&serde_json::Value::Object(object)); - return 0; - } - if !selected_any { - println!("module: {}", entry.module_id); - println!("path: {}", entry.path.display()); - println!("project root: {}", project.root.display()); - println!("functions:"); - for function in &module.functions { - let params = function - .params - .iter() - .map(|param| param.name.as_str()) - .collect::>() - .join(", "); - let kind = match function.signature { - marqdo_ir::SignatureKind::Explicit => "explicit", - marqdo_ir::SignatureKind::Inferred => "inferred", - }; - println!(" {} ({params}) [{kind}]", function.id.name); - } - println!( - "resources: {} formula/code block(s)", - module.resources.len() - ); - return 0; - } - if flags.ast { - println!( - "{}", - serde_json::to_string_pretty(&entry.analysis.document.root).unwrap_or_default() - ); - } - if flags.units { - println!( - "{}", - serde_json::to_string_pretty(&entry.analysis.units.units).unwrap_or_default() - ); - } - if flags.signature { - println!( - "{}", - serde_json::to_string_pretty(&signatures_json(module)).unwrap_or_default() - ); - } - if flags.ir { - println!( - "{}", - serde_json::to_string_pretty(&module.functions).unwrap_or_default() - ); - } - if flags.refs { - println!( - "{}", - serde_json::to_string_pretty(&refs_json(&project)).unwrap_or_default() - ); - } - if flags.platform { - println!( - "{}", - serde_json::to_string_pretty(&PlatformCapabilities::detect()).unwrap_or_default() - ); - } - 0 -} - -/// Validate Markdown reference edges for every loaded document. -/// -/// Links are static references: checking them never executes anything. Broken -/// same-document anchors, missing files and missing target anchors are -/// `ref.unresolved` errors; external HTTP(S) links are accepted as external. fn validate_refs(project: &LoadedProject) -> Vec { let mut diagnostics = Vec::new(); for file in project.files.values() { @@ -595,306 +402,6 @@ fn launch_strict_process( } /// `marqdo run` / `marqdo call`. -pub fn execute( - file: Option<&Path>, - function: Option<&str>, - named_args: &[(String, Value)], - settings: &SandboxSettings, - json: bool, - trace: bool, -) -> i32 { - let command_name = if function.is_some() { "call" } else { "run" }; - let mut project = match load_project(file, json) { - Ok(project) => project, - Err(code) => return code, - }; - if let Err(error) = add_static_plugin_descriptors(&mut project, &settings.plugins) { - if json { - output::print_json(&json!({"success": false, "error": error})); - } else { - eprintln!("error: {error}"); - } - return 2; - } - if project.has_errors() { - if json { - output::print_json(&json!({ - "command": command_name, - "success": false, - "diagnostics": output::diagnostics_json(&project.diagnostics), - })); - } else { - eprint!("{}", output::render_text(&project.diagnostics)); - eprintln!("error: refusing to run a project with compile errors"); - } - return 1; - } - let warnings: Vec = project - .diagnostics - .iter() - .filter(|item| !item.diagnostic.is_error()) - .cloned() - .collect(); - if !json && !warnings.is_empty() { - eprint!("{}", output::render_text(&warnings)); - } - let mode = match settings.sandbox_mode() { - Ok(mode) => mode, - Err(error) => { - eprintln!("error: {error}"); - return 2; - } - }; - if mode == SandboxMode::Strict { - if let Err(error) = settings.strict_preflight() { - if json { - output::print_json(&json!({"success": false, "error": error})); - } else { - eprintln!("error: {error}"); - } - return 2; - } - if marqdo_sandbox::marker_present() { - // We were re-executed by the supervisor: validate the marker set - // before running any project code. - if let Err(reason) = marqdo_sandbox::verify_active() { - if json { - output::print_json(&json!({ - "success": false, - "error": format!("strict isolation verification failed: {reason}"), - })); - } else { - eprintln!("error: strict isolation verification failed: {reason}"); - } - return 1; - } - } else { - let platform = PlatformCapabilities::detect(); - if let Err(error) = marqdo_sandbox::enforce(mode, &platform) { - if json { - output::print_json(&json!({"success": false, "error": error.to_string()})); - } else { - eprintln!("error: {error}"); - } - return 1; - } - return launch_strict_process(&project.root, file, settings); - } - } - let platform = PlatformCapabilities::detect(); - if let Err(error) = marqdo_sandbox::enforce(mode, &platform) { - if json { - output::print_json(&json!({"success": false, "error": error.to_string()})); - } else { - eprintln!("error: {error}"); - } - return 1; - } - let capabilities = match settings.capabilities() { - Ok(capabilities) => capabilities, - Err(error) => { - eprintln!("error: {error}"); - return 2; - } - }; - let stdin = read_stdin(); - let mut host = StdHost::new(mode, capabilities, project.root.clone()).with_stdin(stdin); - if trace || json || settings.trace_file.is_some() { - host = host - .with_trace() - .with_trace_budget(marqdo_host::TraceBudget { - max_events: settings - .trace_max_events - .unwrap_or(marqdo_host::trace::DEFAULT_MAX_TRACE_EVENTS), - max_bytes: settings - .trace_max_bytes - .unwrap_or(marqdo_host::trace::DEFAULT_MAX_TRACE_BYTES), - }); - } - if let Some(fuel) = settings.fuel { - host.budget.fuel = fuel; - } - if let Some(stack) = settings.stack { - host.budget.stack_limit = stack; - } - if let Some(max_output) = settings.max_output { - host.budget.max_output_bytes = max_output; - } - if let Some(timeout) = settings.timeout { - host.budget.deadline = Some(Instant::now() + Duration::from_secs(timeout)); - } - for kernel_path in &settings.kernels { - if let Err(error) = load_kernel_descriptor(&mut host, kernel_path) { - if json { - output::print_json(&json!({"success": false, "error": error})); - } else { - eprintln!("error: {error}"); - } - return 2; - } - } - for plugin_path in &settings.plugins { - if let Err(message) = - load_plugin_into_host(&mut host, plugin_path, settings.trust_native_plugin) - { - if json { - output::print_json(&json!({"success": false, "error": message})); - } else { - eprintln!("error: {message}"); - } - return 1; - } - } - // Expose the complete export names loaded from trusted manifests so the - // runtime resolves exactly those names instead of probing namespaces. - for (name, _signature, digest, package) in host.plugin_exports() { - if project - .program - .external_callables - .iter() - .any(|callable| callable.public_name == name) - { - continue; - } - project - .program - .external_callables - .push(marqdo_ir::callable::CallableDescriptor { - id: marqdo_ir::callable::CallableId(format!("plugin:{package}:{name}")), - public_name: name.clone(), - owner_package: package.clone(), - signature: marqdo_ir::callable::CallableSignature { - params: Vec::new(), - kind: marqdo_ir::SignatureKind::Explicit, - }, - effects_requested: vec!["host".to_string()], - origin: marqdo_ir::callable::CallableOrigin::AbiPlugin { - package, - export: name, - }, - implementation_digest: Some(digest), - source_span: None, - }); - } - let function_name = function.unwrap_or("main").to_string(); - let entry_module = &project.program.modules[&project.entry]; - if entry_module.function(&function_name).is_none() { - eprintln!( - "error: no function named `{function_name}` in {}", - project.entry_file().path.display() - ); - return 1; - } - let runtime_args: Vec = named_args - .iter() - .map(|(name, value)| EvaluatedArg::named(name.clone(), value.clone(), Span::default())) - .collect(); - let memory_limits = MemoryLimits { - max_total_bytes: settings - .max_memory - .unwrap_or(marqdo_runtime::DEFAULT_MAX_TOTAL_BYTES), - max_region_bytes: settings - .max_region_memory - .unwrap_or(marqdo_runtime::DEFAULT_MAX_REGION_BYTES), - }; - let result = run_with_limits( - &project.program, - &mut host, - &project.entry, - &function_name, - runtime_args, - memory_limits, - ); - if let Some(path) = &settings.trace_file { - let status = match &result { - Ok(_) => "ok", - Err(error) => error.code(), - }; - let entry = format!("{}::{}", project.entry, function_name); - if let Err(error) = crate::trace::write(&project, &host, &entry, status, path) { - eprintln!("error: {error}"); - return 1; - } - } - let stdout = host.take_output(); - let stdout_text = String::from_utf8_lossy(&stdout).to_string(); - let stderr = host.take_error(); - let stderr_text = String::from_utf8_lossy(&stderr).to_string(); - let trace_entries = host.trace().to_vec(); - match result { - Ok(outcome) => { - if json { - output::print_json(&json!({ - "command": command_name, - "success": true, - "value": marqdo_value::to_wire(&outcome.value), - "stdout": stdout_text, - "stderr": stderr_text, - "diagnostics": output::diagnostics_json(&project.diagnostics), - "trace": trace_entries, - })); - } else { - use std::io::Write; - if !stderr.is_empty() { - let _ = std::io::stderr().write_all(&stderr); - } - let _ = std::io::stdout().write_all(&stdout); - if function.is_some() && outcome.value != Value::Unit { - println!("{}", outcome.value.display()); - } - if trace { - for entry in &trace_entries { - eprintln!( - "trace: {} {} {}us {}", - entry.op, entry.module, entry.duration_micros, entry.result - ); - } - } - } - 0 - } - Err(error) => { - if json { - output::print_json(&json!({ - "command": command_name, - "success": false, - "stdout": stdout_text, - "stderr": stderr_text, - "error": runtime_error_json(&error, &project), - "trace": trace_entries, - })); - } else { - use std::io::Write; - if !stderr.is_empty() { - let _ = std::io::stderr().write_all(&stderr); - } - let _ = std::io::stdout().write_all(&stdout); - eprint!("{}", render_runtime_error(&error, &project)); - } - 1 - } - } -} - -/// Read piped stdin once at the composition boundary. -/// -/// A terminal stdin is not read, so `marqdo run` never blocks waiting for an -/// interactive EOF. Non-terminal input is a finite pipe/file and is copied into -/// the run-scoped `stdio/stdin` resource. -fn read_stdin() -> Vec { - use std::io::{IsTerminal, Read}; - let mut stdin = std::io::stdin(); - if stdin.is_terminal() { - return Vec::new(); - } - let mut bytes = Vec::new(); - if let Err(error) = stdin.read_to_end(&mut bytes) { - eprintln!("error: cannot read stdin: {error}"); - return Vec::new(); - } - bytes -} - fn load_kernel_descriptor(host: &mut StdHost, path: &Path) -> Result<(), String> { let text = std::fs::read_to_string(path).map_err(|error| { format!( diff --git a/crates/cli/src/commands/check.rs b/crates/cli/src/commands/check.rs new file mode 100644 index 0000000..b4dc8f9 --- /dev/null +++ b/crates/cli/src/commands/check.rs @@ -0,0 +1,68 @@ +//! `marqdo check` command. + +use super::*; + +pub fn check( + file: Option<&Path>, + json: bool, + refs: bool, + plugins: &[PathBuf], + emit: Option<&Path>, +) -> i32 { + let mut project = match load_project(file, json) { + Ok(project) => project, + Err(code) => return code, + }; + if let Err(error) = add_static_plugin_descriptors(&mut project, plugins) { + if json { + output::print_json(&json!({"success": false, "error": error})); + } else { + eprintln!("error: {error}"); + } + return 2; + } + if refs { + let ref_diagnostics = validate_refs(&project); + project.diagnostics.extend(ref_diagnostics); + } + let errors = output::error_count(&project.diagnostics); + if let Some(path) = emit { + if errors > 0 { + let _ = std::fs::remove_file(path); + } else if let Err(error) = crate::analysis::write(&project, path) { + eprintln!("error: {error}"); + return 2; + } + } + if json { + output::print_json(&json!({ + "command": "check", + "success": errors == 0, + "errors": errors, + "diagnostics": output::diagnostics_json(&project.diagnostics), + })); + } else { + let text = output::render_text(&project.diagnostics); + eprint!("{text}"); + if errors == 0 { + let checked = project + .program + .modules + .keys() + .filter(|id| !id.instance.starts_with("std:")) + .count(); + println!("checked {checked} module(s): ok"); + } else { + eprintln!( + "check failed: {} error(s), {} warning(s)", + errors, + project.diagnostics.len() - errors + ); + } + } + if errors == 0 { + 0 + } else { + 1 + } +} diff --git a/crates/cli/src/commands/inspect.rs b/crates/cli/src/commands/inspect.rs new file mode 100644 index 0000000..e9ee715 --- /dev/null +++ b/crates/cli/src/commands/inspect.rs @@ -0,0 +1,132 @@ +//! `marqdo inspect` command. + +use super::*; + +/// Options for `marqdo inspect`. +#[derive(Debug, Clone, Default)] +pub struct InspectFlags { + /// Show the Markdown AST. + pub ast: bool, + /// Show heading units. + pub units: bool, + /// Show inferred/explicit signatures. + pub signature: bool, + /// Show executable IR. + pub ir: bool, + /// Show link reference edges. + pub refs: bool, + /// Show platform capability report. + pub platform: bool, +} + +pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 { + let project = match load_project(file, json) { + Ok(project) => project, + Err(code) => return code, + }; + let entry = project.entry_file(); + let module = &entry.analysis.module; + let selected_any = + flags.ast || flags.units || flags.signature || flags.ir || flags.refs || flags.platform; + if json { + let mut object = serde_json::Map::new(); + object.insert("command".into(), json!("inspect")); + object.insert("module".into(), json!(entry.module_id.to_string())); + if !selected_any { + object.insert("summary".into(), summary_json(&project)); + } + if flags.ast { + object.insert( + "ast".into(), + serde_json::to_value(&entry.analysis.document.root).unwrap_or_default(), + ); + } + if flags.units { + object.insert( + "units".into(), + serde_json::to_value(&entry.analysis.units.units).unwrap_or_default(), + ); + } + if flags.signature { + object.insert("signatures".into(), signatures_json(module)); + } + if flags.ir { + object.insert( + "ir".into(), + serde_json::to_value(&module.functions).unwrap_or_default(), + ); + } + if flags.refs { + object.insert("refs".into(), json!(refs_json(&project))); + } + if flags.platform { + object.insert( + "platform".into(), + serde_json::to_value(PlatformCapabilities::detect()).unwrap_or_default(), + ); + } + output::print_json(&serde_json::Value::Object(object)); + return 0; + } + if !selected_any { + println!("module: {}", entry.module_id); + println!("path: {}", entry.path.display()); + println!("project root: {}", project.root.display()); + println!("functions:"); + for function in &module.functions { + let params = function + .params + .iter() + .map(|param| param.name.as_str()) + .collect::>() + .join(", "); + let kind = match function.signature { + marqdo_ir::SignatureKind::Explicit => "explicit", + marqdo_ir::SignatureKind::Inferred => "inferred", + }; + println!(" {} ({params}) [{kind}]", function.id.name); + } + println!( + "resources: {} formula/code block(s)", + module.resources.len() + ); + return 0; + } + if flags.ast { + println!( + "{}", + serde_json::to_string_pretty(&entry.analysis.document.root).unwrap_or_default() + ); + } + if flags.units { + println!( + "{}", + serde_json::to_string_pretty(&entry.analysis.units.units).unwrap_or_default() + ); + } + if flags.signature { + println!( + "{}", + serde_json::to_string_pretty(&signatures_json(module)).unwrap_or_default() + ); + } + if flags.ir { + println!( + "{}", + serde_json::to_string_pretty(&module.functions).unwrap_or_default() + ); + } + if flags.refs { + println!( + "{}", + serde_json::to_string_pretty(&refs_json(&project)).unwrap_or_default() + ); + } + if flags.platform { + println!( + "{}", + serde_json::to_string_pretty(&PlatformCapabilities::detect()).unwrap_or_default() + ); + } + 0 +} diff --git a/crates/cli/src/commands/run.rs b/crates/cli/src/commands/run.rs new file mode 100644 index 0000000..4cef8c5 --- /dev/null +++ b/crates/cli/src/commands/run.rs @@ -0,0 +1,306 @@ +//! `marqdo run` execution assembly. +//! +//! Child module of `commands`: it may use the parent's project loader and +//! runtime helpers, but keeps the run session out of the command table. + +use super::*; + +pub fn execute( + file: Option<&Path>, + function: Option<&str>, + named_args: &[(String, Value)], + settings: &SandboxSettings, + json: bool, + trace: bool, +) -> i32 { + let command_name = if function.is_some() { "call" } else { "run" }; + let mut project = match load_project(file, json) { + Ok(project) => project, + Err(code) => return code, + }; + if let Err(error) = add_static_plugin_descriptors(&mut project, &settings.plugins) { + if json { + output::print_json(&json!({"success": false, "error": error})); + } else { + eprintln!("error: {error}"); + } + return 2; + } + if project.has_errors() { + if json { + output::print_json(&json!({ + "command": command_name, + "success": false, + "diagnostics": output::diagnostics_json(&project.diagnostics), + })); + } else { + eprint!("{}", output::render_text(&project.diagnostics)); + eprintln!("error: refusing to run a project with compile errors"); + } + return 1; + } + let warnings: Vec = project + .diagnostics + .iter() + .filter(|item| !item.diagnostic.is_error()) + .cloned() + .collect(); + if !json && !warnings.is_empty() { + eprint!("{}", output::render_text(&warnings)); + } + let mode = match settings.sandbox_mode() { + Ok(mode) => mode, + Err(error) => { + eprintln!("error: {error}"); + return 2; + } + }; + if mode == SandboxMode::Strict { + if let Err(error) = settings.strict_preflight() { + if json { + output::print_json(&json!({"success": false, "error": error})); + } else { + eprintln!("error: {error}"); + } + return 2; + } + if marqdo_sandbox::marker_present() { + // We were re-executed by the supervisor: validate the marker set + // before running any project code. + if let Err(reason) = marqdo_sandbox::verify_active() { + if json { + output::print_json(&json!({ + "success": false, + "error": format!("strict isolation verification failed: {reason}"), + })); + } else { + eprintln!("error: strict isolation verification failed: {reason}"); + } + return 1; + } + } else { + let platform = PlatformCapabilities::detect(); + if let Err(error) = marqdo_sandbox::enforce(mode, &platform) { + if json { + output::print_json(&json!({"success": false, "error": error.to_string()})); + } else { + eprintln!("error: {error}"); + } + return 1; + } + return launch_strict_process(&project.root, file, settings); + } + } + let platform = PlatformCapabilities::detect(); + if let Err(error) = marqdo_sandbox::enforce(mode, &platform) { + if json { + output::print_json(&json!({"success": false, "error": error.to_string()})); + } else { + eprintln!("error: {error}"); + } + return 1; + } + let capabilities = match settings.capabilities() { + Ok(capabilities) => capabilities, + Err(error) => { + eprintln!("error: {error}"); + return 2; + } + }; + let stdin = read_stdin(); + let mut host = StdHost::new(mode, capabilities, project.root.clone()).with_stdin(stdin); + if trace || json || settings.trace_file.is_some() { + host = host + .with_trace() + .with_trace_budget(marqdo_host::TraceBudget { + max_events: settings + .trace_max_events + .unwrap_or(marqdo_host::trace::DEFAULT_MAX_TRACE_EVENTS), + max_bytes: settings + .trace_max_bytes + .unwrap_or(marqdo_host::trace::DEFAULT_MAX_TRACE_BYTES), + }); + } + if let Some(fuel) = settings.fuel { + host.budget.fuel = fuel; + } + if let Some(stack) = settings.stack { + host.budget.stack_limit = stack; + } + if let Some(max_output) = settings.max_output { + host.budget.max_output_bytes = max_output; + } + if let Some(timeout) = settings.timeout { + host.budget.deadline = Some(Instant::now() + Duration::from_secs(timeout)); + } + for kernel_path in &settings.kernels { + if let Err(error) = load_kernel_descriptor(&mut host, kernel_path) { + if json { + output::print_json(&json!({"success": false, "error": error})); + } else { + eprintln!("error: {error}"); + } + return 2; + } + } + for plugin_path in &settings.plugins { + if let Err(message) = + load_plugin_into_host(&mut host, plugin_path, settings.trust_native_plugin) + { + if json { + output::print_json(&json!({"success": false, "error": message})); + } else { + eprintln!("error: {message}"); + } + return 1; + } + } + // Expose the complete export names loaded from trusted manifests so the + // runtime resolves exactly those names instead of probing namespaces. + for (name, _signature, digest, package) in host.plugin_exports() { + if project + .program + .external_callables + .iter() + .any(|callable| callable.public_name == name) + { + continue; + } + project + .program + .external_callables + .push(marqdo_ir::callable::CallableDescriptor { + id: marqdo_ir::callable::CallableId(format!("plugin:{package}:{name}")), + public_name: name.clone(), + owner_package: package.clone(), + signature: marqdo_ir::callable::CallableSignature { + params: Vec::new(), + kind: marqdo_ir::SignatureKind::Explicit, + }, + effects_requested: vec!["host".to_string()], + origin: marqdo_ir::callable::CallableOrigin::AbiPlugin { + package, + export: name, + }, + implementation_digest: Some(digest), + source_span: None, + }); + } + let function_name = function.unwrap_or("main").to_string(); + let entry_module = &project.program.modules[&project.entry]; + if entry_module.function(&function_name).is_none() { + eprintln!( + "error: no function named `{function_name}` in {}", + project.entry_file().path.display() + ); + return 1; + } + let runtime_args: Vec = named_args + .iter() + .map(|(name, value)| EvaluatedArg::named(name.clone(), value.clone(), Span::default())) + .collect(); + let memory_limits = MemoryLimits { + max_total_bytes: settings + .max_memory + .unwrap_or(marqdo_runtime::DEFAULT_MAX_TOTAL_BYTES), + max_region_bytes: settings + .max_region_memory + .unwrap_or(marqdo_runtime::DEFAULT_MAX_REGION_BYTES), + }; + let result = run_with_limits( + &project.program, + &mut host, + &project.entry, + &function_name, + runtime_args, + memory_limits, + ); + if let Some(path) = &settings.trace_file { + let status = match &result { + Ok(_) => "ok", + Err(error) => error.code(), + }; + let entry = format!("{}::{}", project.entry, function_name); + if let Err(error) = crate::trace::write(&project, &host, &entry, status, path) { + eprintln!("error: {error}"); + return 1; + } + } + let stdout = host.take_output(); + let stdout_text = String::from_utf8_lossy(&stdout).to_string(); + let stderr = host.take_error(); + let stderr_text = String::from_utf8_lossy(&stderr).to_string(); + let trace_entries = host.trace().to_vec(); + match result { + Ok(outcome) => { + if json { + output::print_json(&json!({ + "command": command_name, + "success": true, + "value": marqdo_value::to_wire(&outcome.value), + "stdout": stdout_text, + "stderr": stderr_text, + "diagnostics": output::diagnostics_json(&project.diagnostics), + "trace": trace_entries, + })); + } else { + use std::io::Write; + if !stderr.is_empty() { + let _ = std::io::stderr().write_all(&stderr); + } + let _ = std::io::stdout().write_all(&stdout); + if function.is_some() && outcome.value != Value::Unit { + println!("{}", outcome.value.display()); + } + if trace { + for entry in &trace_entries { + eprintln!( + "trace: {} {} {}us {}", + entry.op, entry.module, entry.duration_micros, entry.result + ); + } + } + } + 0 + } + Err(error) => { + if json { + output::print_json(&json!({ + "command": command_name, + "success": false, + "stdout": stdout_text, + "stderr": stderr_text, + "error": runtime_error_json(&error, &project), + "trace": trace_entries, + })); + } else { + use std::io::Write; + if !stderr.is_empty() { + let _ = std::io::stderr().write_all(&stderr); + } + let _ = std::io::stdout().write_all(&stdout); + eprint!("{}", render_runtime_error(&error, &project)); + } + 1 + } + } +} + +/// Read piped stdin once at the composition boundary. +/// +/// A terminal stdin is not read, so `marqdo run` never blocks waiting for an +/// interactive EOF. Non-terminal input is a finite pipe/file and is copied into +/// the run-scoped `stdio/stdin` resource. +fn read_stdin() -> Vec { + use std::io::{IsTerminal, Read}; + let mut stdin = std::io::stdin(); + if stdin.is_terminal() { + return Vec::new(); + } + let mut bytes = Vec::new(); + if let Err(error) = stdin.read_to_end(&mut bytes) { + eprintln!("error: cannot read stdin: {error}"); + return Vec::new(); + } + bytes +} diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index 55725a0..412fd7a 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -27,6 +27,8 @@ use crate::resource::{ResourceProvider, ResourceRead, ResourceTable, SharedResou use crate::trace::{EffectTrace, SemanticEvent, TraceBudget, TraceEntry, TraceState}; use marqdo_sandbox::{PlatformCapabilities, SandboxMode}; +mod effects; +mod providers; mod resource_ops; /// Host operations reachable from the language surface. @@ -440,12 +442,6 @@ impl StdHost { &self.semantic_events } - fn next_seq(&mut self) -> u64 { - let seq = self.next_event_seq; - self.next_event_seq += 1; - seq - } - /// Trace capacity state for the writer. pub fn trace_state(&self) -> &TraceState { &self.trace_state @@ -611,152 +607,6 @@ impl StdHost { self.fs.write(&path, &contents, ctx.span)?; Ok(Value::Unit) } - - /// Register an explicitly trusted in-process provider (ADR-0033). - /// - /// In-process providers share the host address space and are not a - /// sandbox; only trusted adapters may be registered. Registration is not a - /// language operation and does not grant access by itself. - pub fn register_resource_provider( - &mut self, - provider: Box, - ) -> Result<(), RuntimeError> { - self.register_provider_checked(provider) - } - - /// Register a trusted C ABI resource provider (ADR-0036). - /// - /// The shared library runs in the host address space and is **trusted**, not - /// sandboxed. Registration still requires the provider-name grant at - /// `resource.open` and is project-mode only. - pub fn register_c_resource_provider( - &mut self, - name: &str, - kinds: &[&str], - library: &std::path::Path, - ) -> Result<(), RuntimeError> { - let kinds = kinds - .iter() - .map(|kind| (*kind).to_string()) - .collect::>(); - let provider = CResourceProvider::open(name, &kinds, library)?; - self.register_provider_checked(Box::new(provider)) - } - - /// Register a trusted C ABI provider from a `marqdo.provider` manifest - /// (ADR-0037). The manifest is host-side installation metadata; language - /// imports cannot install or authorize a provider. - pub fn register_provider_package( - &mut self, - manifest_path: &std::path::Path, - ) -> Result<(), RuntimeError> { - let provider = load_package(manifest_path)?; - self.register_provider_checked(Box::new(provider)) - } - - /// Register a trusted worker-process resource provider (ADR-0035). - /// - /// The helper speaks framed JSON over stdin/stdout and is **not** an OS - /// sandbox; only explicitly trusted helpers may be spawned. - pub fn register_worker_resource_provider( - &mut self, - name: &str, - kinds: &[&str], - program: &std::path::Path, - args: &[String], - ) -> Result<(), RuntimeError> { - let kinds = kinds - .iter() - .map(|kind| (*kind).to_string()) - .collect::>(); - let provider = WorkerResourceProvider::spawn(name, &kinds, program, args)?; - self.register_provider_checked(Box::new(provider)) - } - - fn register_provider_checked( - &mut self, - provider: Box, - ) -> Result<(), RuntimeError> { - if provider.protocol_version() != 1 { - return Err(RuntimeError::new( - ErrorCategory::ResourceUnsupported, - None, - format!( - "resource provider `{}` uses unsupported protocol version {}", - provider.name(), - provider.protocol_version() - ), - )); - } - let name = provider.name().to_string(); - if name.is_empty() || name == "stdio" || name == "file" { - return Err(RuntimeError::new( - ErrorCategory::ResourceUnsupported, - None, - format!("resource provider name `{name}` is reserved or empty"), - )); - } - let kinds = provider.kind_strings(); - if kinds.is_empty() { - return Err(RuntimeError::new( - ErrorCategory::ResourceUnsupported, - None, - format!("resource provider `{name}` declares no kinds"), - )); - } - for kind in &kinds { - if kind.is_empty() || kind == "stdio" || kind == "file" { - return Err(RuntimeError::new( - ErrorCategory::ResourceUnsupported, - None, - format!("resource provider `{name}` declares reserved kind `{kind}`"), - )); - } - if let Some((existing, _)) = self.resource_providers.get(kind) { - return Err(RuntimeError::new( - ErrorCategory::ResourceUnsupported, - None, - format!( - "resource kind `{kind}` is already registered by provider `{existing}`" - ), - )); - } - } - let provider: SharedResourceProvider = std::sync::Arc::new(std::sync::Mutex::new(provider)); - for kind in kinds { - self.resource_providers - .insert(kind, (name.clone(), std::sync::Arc::clone(&provider))); - } - Ok(()) - } - - fn record_resource_effect( - &mut self, - op: &str, - ctx: &ExecutionContext, - started: Instant, - summary: &str, - ) { - let estimate = TraceState::estimate( - "effect", - None, - Some(&ctx.module_id), - Some(summary), - Some(op), - ); - if !self.trace_state.accept(estimate) { - return; - } - let seq = self.next_seq(); - self.trace.record( - seq, - op, - ctx.module_id.clone(), - ctx.span, - started.elapsed(), - summary.to_string(), - ); - } } impl Host for StdHost { diff --git a/crates/marqdo-host/src/host/effects.rs b/crates/marqdo-host/src/host/effects.rs new file mode 100644 index 0000000..af41181 --- /dev/null +++ b/crates/marqdo-host/src/host/effects.rs @@ -0,0 +1,41 @@ +//! Trace/effect bookkeeping helpers for `StdHost`. +//! +//! Child module of `host`; it may use the parent's private trace state. + +use super::*; + +impl StdHost { + pub(crate) fn next_seq(&mut self) -> u64 { + let seq = self.next_event_seq; + self.next_event_seq += 1; + seq + } + + pub(crate) fn record_resource_effect( + &mut self, + op: &str, + ctx: &ExecutionContext, + started: Instant, + summary: &str, + ) { + let estimate = TraceState::estimate( + "effect", + None, + Some(&ctx.module_id), + Some(summary), + Some(op), + ); + if !self.trace_state.accept(estimate) { + return; + } + let seq = self.next_seq(); + self.trace.record( + seq, + op, + ctx.module_id.clone(), + ctx.span, + started.elapsed(), + summary.to_string(), + ); + } +} diff --git a/crates/marqdo-host/src/host/providers.rs b/crates/marqdo-host/src/host/providers.rs new file mode 100644 index 0000000..b1d14d3 --- /dev/null +++ b/crates/marqdo-host/src/host/providers.rs @@ -0,0 +1,127 @@ +//! Trusted resource-provider registration (ADR-0033/0035/0036/0037/0038). +//! +//! Registration is host-side installation metadata; language imports cannot +//! install or authorize a provider. Native libraries and helper processes are +//! trusted, not sandboxed. + +use super::*; + +impl StdHost { + /// Register an explicitly trusted in-process provider (ADR-0033). + /// + /// In-process providers share the host address space and are not a + /// sandbox; only trusted adapters may be registered. Registration is not a + /// language operation and does not grant access by itself. + pub fn register_resource_provider( + &mut self, + provider: Box, + ) -> Result<(), RuntimeError> { + self.register_provider_checked(provider) + } + + /// Register a trusted C ABI resource provider (ADR-0036). + /// + /// The shared library runs in the host address space and is **trusted**, not + /// sandboxed. Registration still requires the provider-name grant at + /// `resource.open` and is project-mode only. + pub fn register_c_resource_provider( + &mut self, + name: &str, + kinds: &[&str], + library: &std::path::Path, + ) -> Result<(), RuntimeError> { + let kinds = kinds + .iter() + .map(|kind| (*kind).to_string()) + .collect::>(); + let provider = CResourceProvider::open(name, &kinds, library)?; + self.register_provider_checked(Box::new(provider)) + } + + /// Register a trusted C ABI provider from a `marqdo.provider` manifest + /// (ADR-0037). The manifest is host-side installation metadata; language + /// imports cannot install or authorize a provider. + pub fn register_provider_package( + &mut self, + manifest_path: &std::path::Path, + ) -> Result<(), RuntimeError> { + let provider = load_package(manifest_path)?; + self.register_provider_checked(Box::new(provider)) + } + + /// Register a trusted worker-process resource provider (ADR-0035). + /// + /// The helper speaks framed JSON over stdin/stdout and is **not** an OS + /// sandbox; only explicitly trusted helpers may be spawned. + pub fn register_worker_resource_provider( + &mut self, + name: &str, + kinds: &[&str], + program: &std::path::Path, + args: &[String], + ) -> Result<(), RuntimeError> { + let kinds = kinds + .iter() + .map(|kind| (*kind).to_string()) + .collect::>(); + let provider = WorkerResourceProvider::spawn(name, &kinds, program, args)?; + self.register_provider_checked(Box::new(provider)) + } + + fn register_provider_checked( + &mut self, + provider: Box, + ) -> Result<(), RuntimeError> { + if provider.protocol_version() != 1 { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + None, + format!( + "resource provider `{}` uses unsupported protocol version {}", + provider.name(), + provider.protocol_version() + ), + )); + } + let name = provider.name().to_string(); + if name.is_empty() || name == "stdio" || name == "file" { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + None, + format!("resource provider name `{name}` is reserved or empty"), + )); + } + let kinds = provider.kind_strings(); + if kinds.is_empty() { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + None, + format!("resource provider `{name}` declares no kinds"), + )); + } + for kind in &kinds { + if kind.is_empty() || kind == "stdio" || kind == "file" { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + None, + format!("resource provider `{name}` declares reserved kind `{kind}`"), + )); + } + if let Some((existing, _)) = self.resource_providers.get(kind) { + return Err(RuntimeError::new( + ErrorCategory::ResourceUnsupported, + None, + format!( + "resource kind `{kind}` is already registered by provider `{existing}`" + ), + )); + } + } + let provider: SharedResourceProvider = std::sync::Arc::new(std::sync::Mutex::new(provider)); + for kind in kinds { + self.resource_providers + .insert(kind, (name.clone(), std::sync::Arc::clone(&provider))); + } + Ok(()) + } +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 652581a..537fa84 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -241,12 +241,12 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL now sorts `.mq.md` by the same relative path key as the CLI. Source/test baseline `0d40de7`; later docs-only commits keep code/test bytes identical. Evidence: [`docs-and-test-migration`](evidence/2026-11-21-docs-and-test-migration.md). -- Module-boundary refactor (review RFC-CM P1): CLI sandbox/capability policy - moved to `crates/cli/src/commands/sandbox.rs`; host resource open dispatch to - `crates/marqdo-host/src/host/resource_ops.rs`; explicitly granted process - execution to `crates/marqdo-host/src/process.rs`. `commands.rs` still owns - run/check/inspect and `host.rs` still owns provider registration; this is a - partial, behavior-preserving split. +- Module-boundary refactor (review RFC-CM P1): CLI split into + `commands/{sandbox,run,check,inspect}.rs`; host split into + `host/{resource_ops,providers,effects}.rs` plus `process.rs`. `commands.rs` + still owns init/fmt/lock/sync/package/tool and `host.rs` still owns the + `Host::invoke` dispatch and capability checks; this is a behavior-preserving + split, not a new crate or backend. - Minimal structure observation/construction (RFC-CM CM-A04, ADR-0023): value-semantics `list.append/concat`, `map.keys/has/get/set/remove`, Unicode scalar `text.codepoints`/`text.from_codepoint`, and non-negative diff --git a/docs/architecture/CURRENT.md b/docs/architecture/CURRENT.md index c6f1168..c6f336a 100644 --- a/docs/architecture/CURRENT.md +++ b/docs/architecture/CURRENT.md @@ -62,9 +62,10 @@ Layer rules: human/machine output. It is not a semantic policy centre. 5. Callable Plugin and Resource Provider share one registry/authorization/audit mechanism, but keep different capability types. -6. CLI sandbox policy is `commands/sandbox.rs`; host open-path policy is - `host/resource_ops.rs`; process execution is `process.rs`. These are child - modules, not new crates or a second backend. +6. CLI policy/commands are `commands/{sandbox,run,check,inspect}.rs`; host + open-path/providers/effects are `host/{resource_ops,providers,effects}.rs`; + process execution is `process.rs`. These are child modules, not new crates + or a second backend. ## 3. Dependency direction and public contracts @@ -127,7 +128,7 @@ that a phase is complete. | P1 | `std:fs/file` read/write/copy and `resource.request` fs metadata/directory operations are implemented; append/seek/watch/recursive walk remain open | open | | P1 | No file append/seek/watch/recursive directory walk | open; future Resource Operation extension | | P1 | JSON/CSV product parsers are implemented; no streaming/multi-line CSV or depth-bounded JSON walker | open | -| P1 | CLI sandbox policy moved to `crates/cli/src/commands/sandbox.rs`; host resource open to `host/resource_ops.rs` and process to `process.rs`; `commands.rs`/`host.rs` still mix run/check/inspect and provider registration | partial refactor, behavior-preserving | +| P1 | CLI split into `commands/{sandbox,run,check,inspect}.rs`; host split into `host/{resource_ops,providers,effects}.rs` plus `process.rs`; `commands.rs` still owns init/fmt/lock/sync/package/tool and `host.rs` still owns `Host::invoke` dispatch | mostly split; package/tool/lock/sync and invoke dispatch remain | | P2 | HTTP parsing is Unicode-codepoint oriented; a general byte body is not the only path | open; convert before a general network release | | P2 | No DNS, TLS, listener or UDP provider | open | | P2 | `std:path`, a regex subset, `std:datetime`, `std:clock`, `std:env` and `std:process` are implemented; no secure random or compression | open | diff --git a/docs/evidence/2026-11-21-module-split.md b/docs/evidence/2026-11-21-module-split.md index d5cb61d..8ffaa61 100644 --- a/docs/evidence/2026-11-21-module-split.md +++ b/docs/evidence/2026-11-21-module-split.md @@ -1,7 +1,7 @@ # Evidence: CLI/Host responsibility split Date: 2026-11-21 (Asia/Shanghai) -Source baseline: `3ef18fb496096d97e3c48ff661f0b2ad00cdcdc3` +Source baseline: `791819a72576f54e406e7dfbbe6ac635f9b1edd2` Repository: `marqdo-cli` RFC item: P1 module boundaries @@ -9,14 +9,19 @@ RFC item: P1 module boundaries | New module | Responsibility | |---|---| -| `crates/cli/src/commands/sandbox.rs` | `SandboxSettings`, mode parsing, strict preflight and CLI-to-`Capabilities` mapping; `commands.rs` re-exports it | +| `crates/cli/src/commands/sandbox.rs` | `SandboxSettings`, mode parsing, strict preflight and CLI-to-`Capabilities` mapping | +| `crates/cli/src/commands/run.rs` | `execute` run-session assembly and `read_stdin` | +| `crates/cli/src/commands/check.rs` | `check` command | +| `crates/cli/src/commands/inspect.rs` | `inspect` command and `InspectFlags` | | `crates/marqdo-host/src/host/resource_ops.rs` | `open_resource_stream` stdio/file/tcp/provider dispatch; child module of `host` | +| `crates/marqdo-host/src/host/providers.rs` | trusted in-process/worker/C-ABI/package provider registration | +| `crates/marqdo-host/src/host/effects.rs` | `next_seq` and `record_resource_effect` trace helpers | | `crates/marqdo-host/src/process.rs` | explicitly granted `process.run` execution, timeout and output caps | This is a **behavior-preserving** refactor: no public CLI flag, host trait -method, builtin, spec or stdlib API changed. No new crate was added. Provider -registration and `commands.rs` run/check/inspect still live in their original -files. +method, builtin, spec or stdlib API changed. No new crate was added. +`commands.rs` still owns init/fmt/lock/sync/package/tool and `host.rs` still +owns `Host::invoke` dispatch and capability checks. ## Commands @@ -31,7 +36,7 @@ python3 tools/pack-stdlib.py PASS ## Not covered -`commands.rs` still contains run/check/inspect/package/tool command bodies -and `host.rs` still contains provider registration and capability dispatch. -A complete split needs a later behavior-preserving change; it is not claimed -here. +`commands.rs` still contains init/fmt/lock/sync/package/tool command bodies +and `host.rs` still contains `Host::invoke` dispatch, capability checks and +register entry points. A complete split needs a later behavior-preserving +change; it is not claimed here.