Files
marqdo-cli/crates/cli/tests/tool_protocol.rs
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

486 lines
17 KiB
Rust

//! External CLI Tool Protocol v1 black-box tests (spec/tool-v1.md).
//!
//! The tool fixture is compiled with rustc from `tests/fixtures/tool_echo.rs`
//! rather than a shell script, so these tests run on Windows and macOS too.
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU32, Ordering};
use std::sync::OnceLock;
static COUNTER: AtomicU32 = AtomicU32::new(0);
struct TempDir(PathBuf);
impl TempDir {
fn new(tag: &str) -> Self {
let id = COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!(
"marqdo-tool-test-{}-{id}-{tag}",
std::process::id()
));
std::fs::create_dir_all(&path).unwrap();
Self(path)
}
fn path(&self) -> &Path {
&self.0
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn binary() -> &'static str {
env!("CARGO_BIN_EXE_marqdo")
}
fn cli(home: &Path, args: &[&str]) -> Output {
Command::new(binary())
.args(args)
.env("MARQDO_TOOL_HOME", home)
.output()
.expect("run marqdo")
}
fn fixture_bytes() -> Option<&'static [u8]> {
static BYTES: OnceLock<Option<Vec<u8>>> = OnceLock::new();
BYTES
.get_or_init(|| {
let source = Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()?
.parent()?
.join("tests/fixtures/tool_echo.rs");
let output = std::env::temp_dir().join(format!(
"marqdo-tool-fixture-{}{}",
std::process::id(),
std::env::consts::EXE_SUFFIX
));
let status = Command::new("rustc")
.args(["--edition", "2021", "-o"])
.arg(&output)
.arg(&source)
.status()
.ok()?;
if !status.success() {
return None;
}
let bytes = std::fs::read(&output).ok()?;
let _ = std::fs::remove_file(&output);
Some(bytes)
})
.as_deref()
}
fn write_tool(dir: &Path, command: &str, _script: &str) -> PathBuf {
let bytes = fixture_bytes().expect("compile the portable tool fixture with rustc");
let package = dir.join(format!("{command}-pkg"));
std::fs::create_dir_all(package.join("bin")).unwrap();
let entry = package
.join("bin")
.join(format!("{command}{}", std::env::consts::EXE_SUFFIX));
std::fs::write(&entry, bytes).unwrap();
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mut permissions = std::fs::metadata(&entry).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&entry, permissions).unwrap();
}
let entrypoint = format!("bin/{command}{}", std::env::consts::EXE_SUFFIX);
let manifest = package.join("tool.json");
std::fs::write(
&manifest,
format!(
r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"{entrypoint}","compatibility":{{"marqdo":">=3.0.0-beta.1,<4.0.0"}}}}"#
),
)
.unwrap();
manifest
}
fn stderr(output: &Output) -> String {
String::from_utf8_lossy(&output.stderr).to_string()
}
fn stdout(output: &Output) -> String {
String::from_utf8_lossy(&output.stdout).to_string()
}
fn repo_root() -> PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("crates/cli has a parent")
.parent()
.expect("crates has a parent")
.to_path_buf()
}
/// Compile one of the checked-in independent consumer samples and package it
/// as a Tool Protocol v1 bundle. Sources live in `examples/tool-samples/` so
/// they are reviewable software, not hidden test strings.
fn write_sample_from_source(dir: &Path, command: &str) -> PathBuf {
let root = repo_root();
let source = root.join(format!("examples/tool-samples/{command}/src/main.rs"));
let package = dir.join(format!("{command}-pkg"));
std::fs::create_dir_all(package.join("bin")).unwrap();
let entry = package
.join("bin")
.join(format!("{command}{}", std::env::consts::EXE_SUFFIX));
let status = Command::new("rustc")
.args(["--edition", "2021", "-o"])
.arg(&entry)
.arg(&source)
.status()
.expect("run rustc for the sample tool");
assert!(status.success(), "rustc failed for {command}");
let entrypoint = format!("bin/{command}{}", std::env::consts::EXE_SUFFIX);
let manifest = package.join("tool.json");
std::fs::write(
&manifest,
format!(
r#"{{"schema":"marqdo.cli-tool","schema_version":1,"name":"demo.{command}","version":"0.1.0","command":"{command}","entrypoint":"{entrypoint}","compatibility":{{"marqdo":">=3.0.0-beta.1,<4.0.0","analysis":[2],"trace":[2]}}}}"#
),
)
.unwrap();
manifest
}
#[test]
fn independent_sample_tools_consume_public_analysis_and_trace() {
let dir = TempDir::new("samples");
let home = dir.path().join("home");
let analysis = dir.path().join("analysis.json");
let trace = dir.path().join("trace.json");
let root = repo_root();
let check = Command::new(binary())
.args([
"check",
"examples/multi-module/index.mq.md",
"--refs",
"--emit",
])
.arg(&analysis)
.current_dir(&root)
.output()
.expect("run check");
assert!(check.status.success(), "check failed: {}", stderr(&check));
let run = Command::new(binary())
.args(["run", "examples/multi-module/index.mq.md", "--trace-file"])
.arg(&trace)
.current_dir(&root)
.output()
.expect("run");
assert!(run.status.success(), "run failed: {}", stderr(&run));
// None of these names exists in the CLI: dispatch must come from the
// installed generic tool registry.
for command in ["sample-view", "sample-knowledge", "sample-proof"] {
let unknown = cli(&home, &[command]);
assert_eq!(unknown.status.code(), Some(2), "{command} must be unknown");
assert!(stderr(&unknown).contains("unknown command"));
let manifest = write_sample_from_source(dir.path(), command);
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(
install.status.code(),
Some(0),
"{command}: {}",
stderr(&install)
);
}
let view = cli(
&home,
&["sample-view", "--analysis", analysis.to_str().unwrap()],
);
assert_eq!(view.status.code(), Some(0), "{}", stderr(&view));
let text = stdout(&view);
assert!(
text.contains("sample-view schema=marqdo.analysis version=2"),
"{text}"
);
assert!(text.contains("modules="), "{text}");
let knowledge = cli(
&home,
&["sample-knowledge", "--trace", trace.to_str().unwrap()],
);
assert_eq!(knowledge.status.code(), Some(0), "{}", stderr(&knowledge));
let text = stdout(&knowledge);
assert!(
text.contains("sample-knowledge schema=marqdo.trace version=2"),
"{text}"
);
assert!(text.contains("status=ok"), "{text}");
let proof = cli(
&home,
&[
"sample-proof",
"--analysis",
analysis.to_str().unwrap(),
"--trace",
trace.to_str().unwrap(),
],
);
assert_eq!(proof.status.code(), Some(0), "{}", stderr(&proof));
let text = stdout(&proof);
assert!(text.contains("sample-proof bound=true"), "{text}");
assert!(text.contains("digest=sha256:"), "{text}");
for command in ["sample-view", "sample-knowledge", "sample-proof"] {
let removed = cli(&home, &["tool", "remove", command]);
assert_eq!(removed.status.code(), Some(0), "{}", stderr(&removed));
}
}
#[test]
fn install_dispatch_list_remove_without_core_knowledge_of_the_name() {
let dir = TempDir::new("roundtrip");
let home = dir.path().join("home");
let manifest = write_tool(
dir.path(),
"benchmark",
"#!/bin/sh\nfor a in \"$@\"; do printf 'arg=%s\\n' \"$a\"; done\nprintf 'protocol=%s\\n' \"$MARQDO_TOOL_PROTOCOL\"\nexit 7\n",
);
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(install.status.code(), Some(0), "{}", stderr(&install));
let listed = cli(&home, &["tool", "list"]);
assert!(stdout(&listed).contains("benchmark 0.1.0"));
let output = cli(&home, &["benchmark", "run", ".", "空格"]);
assert_eq!(output.status.code(), Some(7));
let text = stdout(&output);
assert!(text.contains("arg=run"));
assert!(text.contains("arg=."));
assert!(text.contains("arg=空格"));
assert!(text.contains("protocol=1"));
let removed = cli(&home, &["tool", "remove", "benchmark"]);
assert_eq!(removed.status.code(), Some(0));
let unknown = cli(&home, &["benchmark"]);
assert_eq!(unknown.status.code(), Some(2));
assert!(stderr(&unknown).contains("unknown command"));
}
#[test]
fn invalid_manifests_and_path_escapes_are_rejected() {
let dir = TempDir::new("invalid");
let home = dir.path().join("home");
let manifest = write_tool(dir.path(), "lintx", "#!/bin/sh\nexit 0\n");
let builtin = std::fs::read_to_string(&manifest)
.unwrap()
.replace("\"command\":\"lintx\"", "\"command\":\"run\"");
let builtin_manifest = dir.path().join("builtin.json");
std::fs::write(&builtin_manifest, builtin).unwrap();
let output = cli(
&home,
&["tool", "install", builtin_manifest.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
assert!(stderr(&output).contains("built-in"));
let traversal = std::fs::read_to_string(&manifest).unwrap().replace(
&format!("bin/lintx{}", std::env::consts::EXE_SUFFIX),
"../outside",
);
let traversal_manifest = dir.path().join("traversal.json");
std::fs::write(&traversal_manifest, traversal).unwrap();
let output = cli(
&home,
&["tool", "install", traversal_manifest.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
let incompatible = std::fs::read_to_string(&manifest)
.unwrap()
.replace(">=3.0.0-beta.1,<4.0.0", ">=99.0");
let incompatible_manifest = dir.path().join("incompatible.json");
std::fs::write(&incompatible_manifest, incompatible).unwrap();
let output = cli(
&home,
&["tool", "install", incompatible_manifest.to_str().unwrap()],
);
assert_eq!(output.status.code(), Some(1));
assert!(stderr(&output).contains("requires marqdo"));
}
#[test]
fn tampered_binary_and_path_hijack_are_not_executed() {
let dir = TempDir::new("security");
let home = dir.path().join("home");
let manifest = write_tool(dir.path(), "custom-abc", "#!/bin/sh\nexit 0\n");
assert_eq!(
cli(&home, &["tool", "install", manifest.to_str().unwrap()])
.status
.code(),
Some(0)
);
let installed = home
.join("custom-abc")
.join("bin")
.join(format!("custom-abc{}", std::env::consts::EXE_SUFFIX));
std::fs::write(&installed, "#!/bin/sh\nexit 99\n").unwrap();
let tampered = cli(&home, &["custom-abc"]);
assert_eq!(tampered.status.code(), Some(1));
assert!(stderr(&tampered).contains("hash mismatch"));
// A PATH program with the marqdo prefix is not implicitly a tool.
let path_dir = dir.path().join("path");
std::fs::create_dir_all(&path_dir).unwrap();
let hijack = path_dir.join(format!("marqdo-hijack{}", std::env::consts::EXE_SUFFIX));
std::fs::write(&hijack, b"not a registered tool").unwrap();
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mut permissions = std::fs::metadata(&hijack).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&hijack, permissions).unwrap();
}
let output = Command::new(binary())
.arg("hijack")
.env("MARQDO_TOOL_HOME", &home)
.env("PATH", &path_dir)
.output()
.unwrap();
assert_eq!(output.status.code(), Some(2));
assert!(stderr(&output).contains("unknown command"));
}
#[test]
fn protocol_negotiation_accepts_declared_versions_and_rejects_disjoint_ones() {
let dir = TempDir::new("protocols");
let home = dir.path().join("home");
let manifest = write_tool(
dir.path(),
"proto",
"#!/bin/sh\nprintf 'analysis=%s\\ntrace=%s\\n' \"$MARQDO_PROTOCOL_ANALYSIS\" \"$MARQDO_PROTOCOL_TRACE\"\n",
);
let text = std::fs::read_to_string(&manifest).unwrap().replace(
"\"marqdo\":\">=3.0.0-beta.1,<4.0.0\"",
"\"marqdo\":\">=3.0.0-beta.1,<4.0.0\",\"analysis\":[2],\"trace\":[2]",
);
std::fs::write(&manifest, text).unwrap();
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(install.status.code(), Some(0), "{}", stderr(&install));
let output = cli(&home, &["proto"]);
assert_eq!(output.status.code(), Some(7), "{}", stderr(&output));
let text = stdout(&output);
assert!(text.contains("analysis=2"), "{text}");
assert!(text.contains("trace=2"), "{text}");
for (compat, tag) in [
("\"analysis\":[99]", "analysis-disjoint"),
("\"analysis\":[]", "analysis-empty"),
("\"trace\":[9]", "trace-disjoint"),
] {
let command = format!("bad-{tag}");
let manifest = write_tool(dir.path(), &command, "#!/bin/sh\nexit 0\n");
let text = std::fs::read_to_string(&manifest).unwrap().replace(
"\"marqdo\":\">=3.0.0-beta.1,<4.0.0\"",
&format!("\"marqdo\":\">=3.0.0-beta.1,<4.0.0\",{compat}"),
);
std::fs::write(&manifest, text).unwrap();
let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(output.status.code(), Some(1), "{tag}");
assert!(
stderr(&output).contains("protocol_incompatible"),
"{tag}: {}",
stderr(&output)
);
}
}
#[test]
fn tampering_any_bundle_file_or_adding_an_unlisted_file_is_rejected() {
let dir = TempDir::new("bundle");
let home = dir.path().join("home");
let manifest = write_tool(dir.path(), "bundletool", "#!/bin/sh\nprintf 'entry\\n'\n");
let package = manifest.parent().unwrap();
std::fs::create_dir_all(package.join("lib")).unwrap();
std::fs::write(package.join("lib/helper.sh"), "echo helper\n").unwrap();
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(install.status.code(), Some(0), "{}", stderr(&install));
let installed = home.join("bundletool");
// Tamper with a non-entry file only.
std::fs::write(installed.join("lib/helper.sh"), "echo tampered\n").unwrap();
let run = cli(&home, &["bundletool"]);
assert_eq!(run.status.code(), Some(1));
assert!(
stderr(&run).contains("bundle hash mismatch"),
"{}",
stderr(&run)
);
// Reinstall, then add an unlisted file.
assert_eq!(
cli(&home, &["tool", "remove", "bundletool"]).status.code(),
Some(0)
);
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(install.status.code(), Some(0));
std::fs::write(installed.join("lib/extra.sh"), "echo extra\n").unwrap();
let run = cli(&home, &["bundletool"]);
assert_eq!(run.status.code(), Some(1));
assert!(
stderr(&run).contains("bundle hash mismatch"),
"{}",
stderr(&run)
);
}
#[test]
fn a_root_record_json_in_the_source_package_is_rejected() {
let dir = TempDir::new("reserved-record");
let home = dir.path().join("home");
let manifest = write_tool(dir.path(), "reserved", "#!/bin/sh\nexit 0\n");
let package = manifest.parent().unwrap();
std::fs::write(package.join("record.json"), "{}").unwrap();
let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(output.status.code(), Some(1));
assert!(stderr(&output).contains("must not contain a root record.json"));
}
#[test]
fn beta_core_requires_an_explicit_prerelease_compatible_range() {
let dir = TempDir::new("prerelease-range");
let home = dir.path().join("home");
let core = env!("CARGO_PKG_VERSION");
// The shipped example range opt-in must install on this real core.
let manifest = write_tool(dir.path(), "prerelease", "#!/bin/sh\nexit 0\n");
let install = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(install.status.code(), Some(0), "{}", stderr(&install));
if core.contains('-') {
// SemVer: a stable-only requirement must not silently accept a
// prerelease core. The operator has to opt in with a prerelease range.
let manifest = write_tool(dir.path(), "stableonly", "#!/bin/sh\nexit 0\n");
let text = std::fs::read_to_string(&manifest)
.unwrap()
.replace(">=3.0.0-beta.1,<4.0.0", ">=3.0.0,<4.0.0");
std::fs::write(&manifest, text).unwrap();
let output = cli(&home, &["tool", "install", manifest.to_str().unwrap()]);
assert_eq!(
output.status.code(),
Some(1),
"a stable-only range must reject prerelease core {core}: {}",
stderr(&output)
);
assert!(
stderr(&output).contains("requires marqdo"),
"{}",
stderr(&output)
);
}
}