refactor(cli,host): split command entry points and provider/effects modules

This commit is contained in:
Marqdo Agent committed 2026-11-21 08:54:29 +08:00
1 parent 791819a725
commit 550e66b1e2
10 files changed
+708 -671

No files matched your search

+7 -500
View File
@@ -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<marqdo_ir::callable::CallableSignature,
}
/// `marqdo check`.
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
}
}
/// 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::<Vec<_>>()
.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<FileDiagnostic> {
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<FileDiagnostic> = 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<EvaluatedArg> = 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<u8> {
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!(
+68
View File
@@ -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
}
}
+132
View File
@@ -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::<Vec<_>>()
.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
}
+306
View File
@@ -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<FileDiagnostic> = 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<EvaluatedArg> = 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<u8> {
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
}
+2 -152
View File
@@ -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<dyn ResourceProvider>,
) -> 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::<Vec<_>>();
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::<Vec<_>>();
let provider = WorkerResourceProvider::spawn(name, &kinds, program, args)?;
self.register_provider_checked(Box::new(provider))
}
fn register_provider_checked(
&mut self,
provider: Box<dyn ResourceProvider>,
) -> 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 {
+41
View File
@@ -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(),
);
}
}
+127
View File
@@ -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<dyn ResourceProvider>,
) -> 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::<Vec<_>>();
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::<Vec<_>>();
let provider = WorkerResourceProvider::spawn(name, &kinds, program, args)?;
self.register_provider_checked(Box::new(provider))
}
fn register_provider_checked(
&mut self,
provider: Box<dyn ResourceProvider>,
) -> 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(())
}
}
+6 -6
View File
@@ -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
+5 -4
View File
@@ -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 |
+14 -9
View File
@@ -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.