From 4ce37afb393ac81baecbeca84c0ac57f5ea053c4 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 11:50:27 +0800 Subject: [PATCH] feat(m0.6-r6): release examples, public schemas and cross-platform CI - add runnable examples for an unknown-name Tool, multi-export plugin, external kernel provider and same-name multi-version packages - add JSON Schemas for Analysis v1, Trace v1 and Tool v1 and validate them in CI - extend CI with protocol/consumer smoke tests and a Windows/macOS cargo check - add --kernel provider descriptors and R6 example integration tests - document the examples and update M0.6 status --- .github/workflows/ci.yml | 48 ++++++++- .gitignore | 1 + Cargo.lock | 1 + README.md | 14 ++- crates/cli/src/commands.rs | 42 ++++++++ crates/cli/src/main.rs | 4 + crates/cli/tests/examples_r6.rs | 97 +++++++++++++++++++ crates/marqdo-foreign/Cargo.toml | 1 + crates/marqdo-foreign/src/lib.rs | 8 +- docs/STATUS.md | 2 +- examples/kernel-mock/README.md | 16 +++ examples/kernel-mock/demo.mq.md | 11 +++ examples/kernel-mock/kernel.json | 7 ++ examples/kernel-mock/mocklang | 5 + examples/packages-multi-version/README.md | 19 ++++ examples/packages-multi-version/index.mq.md | 15 +++ examples/packages-multi-version/marqdo.yaml | 8 ++ .../packages/geometry-v1/index.mq.md | 3 + .../packages/geometry-v1/marqdo.yaml | 3 + .../packages/geometry-v2/index.mq.md | 3 + .../packages/geometry-v2/marqdo.yaml | 3 + examples/plugin-multi-export/README.md | 17 ++++ examples/plugin-multi-export/build.sh | 17 ++++ .../plugin-multi-export/plugin-call.mq.md | 9 ++ examples/plugin-multi-export/plugin.yaml | 18 ++++ examples/tool-unknown-name/README.md | 19 ++++ .../tool-unknown-name/bin/marqdo-benchmark | 8 ++ examples/tool-unknown-name/tool.json | 11 +++ spec/schemas/analysis-v1.schema.json | 52 ++++++++++ spec/schemas/tool-v1.schema.json | 25 +++++ spec/schemas/trace-v1.schema.json | 55 +++++++++++ 31 files changed, 537 insertions(+), 5 deletions(-) create mode 100644 crates/cli/tests/examples_r6.rs create mode 100644 examples/kernel-mock/README.md create mode 100644 examples/kernel-mock/demo.mq.md create mode 100644 examples/kernel-mock/kernel.json create mode 100755 examples/kernel-mock/mocklang create mode 100644 examples/packages-multi-version/README.md create mode 100644 examples/packages-multi-version/index.mq.md create mode 100644 examples/packages-multi-version/marqdo.yaml create mode 100644 examples/packages-multi-version/packages/geometry-v1/index.mq.md create mode 100644 examples/packages-multi-version/packages/geometry-v1/marqdo.yaml create mode 100644 examples/packages-multi-version/packages/geometry-v2/index.mq.md create mode 100644 examples/packages-multi-version/packages/geometry-v2/marqdo.yaml create mode 100644 examples/plugin-multi-export/README.md create mode 100755 examples/plugin-multi-export/build.sh create mode 100644 examples/plugin-multi-export/plugin-call.mq.md create mode 100644 examples/plugin-multi-export/plugin.yaml create mode 100644 examples/tool-unknown-name/README.md create mode 100755 examples/tool-unknown-name/bin/marqdo-benchmark create mode 100644 examples/tool-unknown-name/tool.json create mode 100644 spec/schemas/analysis-v1.schema.json create mode 100644 spec/schemas/tool-v1.schema.json create mode 100644 spec/schemas/trace-v1.schema.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f6c9959..bd48450 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,16 +24,62 @@ jobs: run: cargo clippy --workspace --all-targets -- -D warnings - name: Tests run: cargo test --workspace - - name: Smoke test the CLI examples + - name: Validate public JSON schemas + run: | + python3 - <<'PY' + import json, pathlib + for path in pathlib.Path("spec/schemas").glob("*.json"): + json.loads(path.read_text()) + print("schemas parse") + PY + - name: Smoke test the CLI, protocols and examples run: | cargo build -p marqdo-cli ./target/debug/marqdo check examples/factorial.mq.md ./target/debug/marqdo call examples/factorial.mq.md 阶乘 --arg n=5 ./target/debug/marqdo call examples/math.mq.md 计算圆面积 ./target/debug/marqdo inspect examples/references.mq.md --refs + ./target/debug/marqdo check examples/multi-module/index.mq.md --refs \ + --emit /tmp/marqdo-analysis.json + ./target/debug/marqdo run examples/hello.mq.md \ + --trace-file /tmp/marqdo-trace.json + python3 tests/consumers/analysis_consumer.py /tmp/marqdo-analysis.json + python3 - <<'PY' + import json + json.load(open("/tmp/marqdo-trace.json")) + print("trace parses") + PY + ./target/debug/marqdo run examples/packages-multi-version/index.mq.md + ./target/debug/marqdo run examples/kernel-mock/demo.mq.md \ + --kernel examples/kernel-mock/kernel.json --allow-foreign + export MARQDO_TOOL_HOME="$(mktemp -d)" + ./target/debug/marqdo tool install examples/tool-unknown-name/tool.json + ./target/debug/marqdo benchmark run . + ./target/debug/marqdo tool remove benchmark ./examples/plugin-demo/build.sh ./target/debug/marqdo plugin inspect examples/plugin-demo ./target/debug/marqdo run examples/plugin-demo/plugin-call.mq.md \ --plugin examples/plugin-demo \ --trust-native-plugin \ --allow-plugin demo.solver + ./examples/plugin-multi-export/build.sh + ./target/debug/marqdo check examples/plugin-multi-export/plugin-call.mq.md \ + --plugin examples/plugin-multi-export + ./target/debug/marqdo run examples/plugin-multi-export/plugin-call.mq.md \ + --plugin examples/plugin-multi-export \ + --trust-native-plugin \ + --allow-plugin demo.solver + + cross-platform: + name: cargo check (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [windows-latest, macos-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + - name: Check all targets + run: cargo check --workspace --all-targets diff --git a/.gitignore b/.gitignore index e66e40a..0c5c0f1 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ # Built plugin artifacts examples/plugin-demo/solver.so +examples/plugin-multi-export/solver.so diff --git a/Cargo.lock b/Cargo.lock index f0b7fb6..995fe0b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -363,6 +363,7 @@ dependencies = [ "libc", "marqdo-span", "marqdo-value", + "serde", "serde_json", "tempfile", "thiserror", diff --git a/README.md b/README.md index 1bfa3d1..c71b3ac 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,8 @@ tests/ conformance/negative corpus (see tests/README.md) [`package-format.md`](spec/package-format.md), [`plugin-abi.md`](spec/plugin-abi.md), [`math.md`](spec/math.md), [`foreign.md`](spec/foreign.md), [`tool-v1.md`](spec/tool-v1.md), - [`analysis-v1.md`](spec/analysis-v1.md), [`trace-v1.md`](spec/trace-v1.md). + [`analysis-v1.md`](spec/analysis-v1.md), [`trace-v1.md`](spec/trace-v1.md); + JSON Schemas in [`spec/schemas/`](spec/schemas/). * [`tests/README.md`](tests/README.md) — conformance corpus and `UPDATE_GOLDENS` workflow. @@ -198,6 +199,9 @@ marqdo run examples/hello.mq.md marqdo call examples/factorial.mq.md 数学.阶乘 --arg n=5 marqdo run examples/multi-module/index.mq.md marqdo run examples/python-foreign.mq.md --allow-foreign # needs python3 or node +marqdo run examples/packages-multi-version/index.mq.md +marqdo run examples/kernel-mock/demo.mq.md \ + --kernel examples/kernel-mock/kernel.json --allow-foreign marqdo inspect examples/references.mq.md --refs marqdo inspect examples/hello.mq.md --platform # strict: unavailable @@ -205,6 +209,14 @@ marqdo inspect examples/hello.mq.md --platform # strict: unavailable marqdo plugin inspect examples/plugin-demo marqdo run examples/plugin-demo/plugin-call.mq.md \ --plugin examples/plugin-demo --trust-native-plugin --allow-plugin demo.solver + +./examples/plugin-multi-export/build.sh +marqdo run examples/plugin-multi-export/plugin-call.mq.md \ + --plugin examples/plugin-multi-export --trust-native-plugin --allow-plugin demo.solver + +marqdo tool install examples/tool-unknown-name/tool.json +marqdo benchmark run . +marqdo tool remove benchmark ``` ## References diff --git a/crates/cli/src/commands.rs b/crates/cli/src/commands.rs index 5decf53..de22ea5 100644 --- a/crates/cli/src/commands.rs +++ b/crates/cli/src/commands.rs @@ -40,6 +40,8 @@ pub struct SandboxSettings { pub trust_native_plugin: bool, /// Optional Trace v1 output path. pub trace_file: Option, + /// External foreign-kernel descriptor paths. + pub kernels: Vec, } impl SandboxSettings { @@ -698,6 +700,16 @@ pub fn execute( 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) @@ -822,6 +834,36 @@ pub fn execute( } } +fn load_kernel_descriptor(host: &mut StdHost, path: &Path) -> Result<(), String> { + let text = std::fs::read_to_string(path).map_err(|error| { + format!( + "cannot read kernel descriptor `{}`: {error}", + path.display() + ) + })?; + let mut descriptor: marqdo_foreign::KernelDescriptor = serde_json::from_str(&text) + .map_err(|error| format!("invalid kernel descriptor `{}`: {error}", path.display()))?; + if descriptor.builtin { + return Err("external kernel descriptors must not set `builtin: true`".to_string()); + } + if descriptor.entrypoint.is_relative() { + let base = path.parent().unwrap_or_else(|| Path::new(".")); + descriptor.entrypoint = base.join(&descriptor.entrypoint); + } + descriptor.entrypoint = descriptor + .entrypoint + .canonicalize() + .map_err(|error| format!("cannot open kernel provider: {error}"))?; + if !descriptor.entrypoint.is_file() { + return Err(format!( + "kernel provider executable `{}` does not exist", + descriptor.entrypoint.display() + )); + } + host.register_kernel(descriptor) + .map_err(|error| format!("{}: {}", error.code(), error.message)) +} + fn load_plugin_into_host( host: &mut StdHost, path: &Path, diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 84e019f..ade6d99 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -101,6 +101,9 @@ struct SandboxArgs { /// Write a versioned Trace v1 file for this run. #[arg(long = "trace-file", value_name = "PATH")] trace_file: Option, + /// Register an external foreign-kernel provider (repeatable). + #[arg(long = "kernel", value_name = "PATH")] + kernel: Vec, /// Explicitly trust in-process native plugin loading (unsafe by nature). #[arg(long = "trust-native-plugin")] trust_native_plugin: bool, @@ -121,6 +124,7 @@ impl SandboxArgs { plugins: self.plugin.clone(), trust_native_plugin: self.trust_native_plugin, trace_file: self.trace_file.clone(), + kernels: self.kernel.clone(), } } } diff --git a/crates/cli/tests/examples_r6.rs b/crates/cli/tests/examples_r6.rs new file mode 100644 index 0000000..b27f22a --- /dev/null +++ b/crates/cli/tests/examples_r6.rs @@ -0,0 +1,97 @@ +//! R6 integration examples that do not require an official external repo. +#![cfg(unix)] + +use std::path::Path; +use std::process::{Command, Output}; + +fn repo() -> &'static Path { + Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .unwrap() + .parent() + .unwrap() +} + +fn cli(args: &[&str]) -> Output { + Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(args) + .current_dir(repo()) + .output() + .expect("run marqdo") +} + +fn stderr(output: &Output) -> String { + String::from_utf8_lossy(&output.stderr).to_string() +} + +#[test] +fn multi_version_packages_run_without_an_implicit_override() { + let output = cli(&["run", "examples/packages-multi-version/index.mq.md"]); + assert_eq!(output.status.code(), Some(0), "{}", stderr(&output)); + assert_eq!(String::from_utf8_lossy(&output.stdout), "1\n2\n"); +} + +#[test] +fn external_kernel_provider_runs_without_core_changes() { + let output = cli(&[ + "run", + "examples/kernel-mock/demo.mq.md", + "--kernel", + "examples/kernel-mock/kernel.json", + "--allow-foreign", + ]); + assert_eq!(output.status.code(), Some(0), "{}", stderr(&output)); + assert_eq!(String::from_utf8_lossy(&output.stdout), "42\n"); +} + +#[test] +fn unknown_tool_name_installs_and_dispatches() { + let home = std::env::temp_dir().join(format!( + "marqdo-r6-tool-home-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + let install = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["tool", "install", "examples/tool-unknown-name/tool.json"]) + .env("MARQDO_TOOL_HOME", &home) + .current_dir(repo()) + .output() + .unwrap(); + assert_eq!(install.status.code(), Some(0), "{}", stderr(&install)); + let run = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["benchmark", "run", "."]) + .env("MARQDO_TOOL_HOME", &home) + .current_dir(repo()) + .output() + .unwrap(); + assert_eq!(run.status.code(), Some(0), "{}", stderr(&run)); + assert!(String::from_utf8_lossy(&run.stdout).contains("arg=run")); + let remove = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["tool", "remove", "benchmark"]) + .env("MARQDO_TOOL_HOME", &home) + .current_dir(repo()) + .output() + .unwrap(); + assert_eq!(remove.status.code(), Some(0), "{}", stderr(&remove)); + let _ = std::fs::remove_dir_all(home); +} + +#[test] +fn public_schemas_are_valid_json_and_versioned() { + for name in ["analysis-v1", "trace-v1", "tool-v1"] { + let path = repo() + .join("spec/schemas") + .join(format!("{name}.schema.json")); + let schema: serde_json::Value = + serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap(); + assert_eq!( + schema["$schema"], + "https://json-schema.org/draft/2020-12/schema" + ); + assert!(schema["title"].is_string()); + assert!(schema["type"].as_str() == Some("object")); + } +} diff --git a/crates/marqdo-foreign/Cargo.toml b/crates/marqdo-foreign/Cargo.toml index fa2a0ec..180899b 100644 --- a/crates/marqdo-foreign/Cargo.toml +++ b/crates/marqdo-foreign/Cargo.toml @@ -14,6 +14,7 @@ tempfile = { workspace = true } [dependencies] marqdo-span = { workspace = true } marqdo-value = { workspace = true } +serde = { workspace = true } serde_json = { workspace = true } thiserror = { workspace = true } diff --git a/crates/marqdo-foreign/src/lib.rs b/crates/marqdo-foreign/src/lib.rs index 8aed993..c6b18a2 100644 --- a/crates/marqdo-foreign/src/lib.rs +++ b/crates/marqdo-foreign/src/lib.rs @@ -74,7 +74,7 @@ pub const SUPPORTED_LANGUAGES: [&str; 2] = ["python", "javascript"]; /// /// Descriptors are metadata; they do not grant process/filesystem access. The /// host still requires an explicit foreign grant before invoking one. -#[derive(Debug, Clone, PartialEq, Eq)] +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] pub struct KernelDescriptor { /// Stable provider id (`python`, `javascript`, `mocklang`, ...). pub provider_id: String, @@ -86,10 +86,14 @@ pub struct KernelDescriptor { /// providers must point at an explicit executable. pub entrypoint: PathBuf, /// Content digest of the external provider program, when known. + #[serde(default, skip_serializing_if = "Option::is_none")] pub digest: Option, /// Advisory capability requests; never grants. + #[serde(default)] pub permissions_requested: Vec, - /// Whether this is one of the built-in Python/Node providers. + /// Whether this is one of the built-in Python/Node providers. External + /// descriptors must leave this false. + #[serde(default)] pub builtin: bool, } diff --git a/docs/STATUS.md b/docs/STATUS.md index 7b8fd0c..59de265 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -45,7 +45,7 @@ providers). | R3 Tool Protocol | **Done** | `tool install/list/remove`; unknown-command fallback; atomic local install; SHA/tamper checks; black-box tests for arbitrary names, Unicode args, conflicts, traversal and PATH hijacking | | R4 Analysis/Trace v1 | **Done** | `check --emit` Analysis v1; `run/call --trace-file` Trace v1; deterministic schema tests; independent Python consumer; stale-artifact removal; value redaction | | R5 environment/isolation | **Partial** | Pinned Git fetch/cache, transitive `@alias` resolution, atomic `.marqdo/env` materialization, foreign process-group cleanup. Strict OS isolation remains explicitly unavailable (fail-closed) | -| R6 release/consumers | Not started | — | +| R6 release/consumers | **Done for Linux** | examples for unknown-name Tool, multi-export plugin, external kernel and multi-version packages; Analysis/Trace/Tool JSON Schemas; CI Linux gate + Windows/macOS `cargo check`; R6 example tests | Reproduce the evidence: diff --git a/examples/kernel-mock/README.md b/examples/kernel-mock/README.md new file mode 100644 index 0000000..9198759 --- /dev/null +++ b/examples/kernel-mock/README.md @@ -0,0 +1,16 @@ +# External kernel provider example + +`mocklang` is not built into `marqdo-foreign`. The descriptor registers it at +run time without changing interpreter or host source: + +```sh +marqdo run examples/kernel-mock/demo.mq.md \ + --kernel examples/kernel-mock/kernel.json \ + --allow-foreign +``` + +The `mocklang` executable receives the source file path as argv[1] and the +versioned request envelope on stdin. For `foreign.call` it must print exactly +one typed wire value on stdout. A missing provider or wire version is +`kernel.unavailable`; the `Code` value itself remains inert until the explicit +call. diff --git a/examples/kernel-mock/demo.mq.md b/examples/kernel-mock/demo.mq.md new file mode 100644 index 0000000..0244d9c --- /dev/null +++ b/examples/kernel-mock/demo.mq.md @@ -0,0 +1,11 @@ +## main + +### 代码 + +```mocklang +ignored by the mock provider +``` + +**结果 = foreign.call(ref("#代码"), {})** + +> 打印(结果) diff --git a/examples/kernel-mock/kernel.json b/examples/kernel-mock/kernel.json new file mode 100644 index 0000000..ee65b37 --- /dev/null +++ b/examples/kernel-mock/kernel.json @@ -0,0 +1,7 @@ +{ + "provider_id": "mocklang", + "languages": ["mocklang", "mock"], + "wire_version": 1, + "entrypoint": "./mocklang", + "permissions_requested": [] +} diff --git a/examples/kernel-mock/mocklang b/examples/kernel-mock/mocklang new file mode 100755 index 0000000..73901d2 --- /dev/null +++ b/examples/kernel-mock/mocklang @@ -0,0 +1,5 @@ +#!/bin/sh +# Minimal external kernel provider: consume the request envelope, then emit one +# typed wire value. The source file path is argv[1]. +cat >/dev/null +printf '%s' '{"type":"int","decimal":"42"}' diff --git a/examples/packages-multi-version/README.md b/examples/packages-multi-version/README.md new file mode 100644 index 0000000..8f54883 --- /dev/null +++ b/examples/packages-multi-version/README.md @@ -0,0 +1,19 @@ +# Multi-version package example + +Two directories declare the same package name `geometry` at versions `1.0.0` +and `2.0.0`. They receive different package-instance ids and different +`ModuleId`s; importing both aliases is not an implicit override. + +```sh +marqdo run examples/packages-multi-version/index.mq.md +marqdo lock +``` + +`marqdo lock` must be run from the example directory because it discovers the +project from the current working directory: + +```sh +(cd examples/packages-multi-version && ../../target/debug/marqdo lock) +``` + +The lock records both content-addressed instances; no version silently wins. diff --git a/examples/packages-multi-version/index.mq.md b/examples/packages-multi-version/index.mq.md new file mode 100644 index 0000000..e66593e --- /dev/null +++ b/examples/packages-multi-version/index.mq.md @@ -0,0 +1,15 @@ +--- +import: + geometry_v1: "@geometry_v1" + geometry_v2: "@geometry_v2" +--- + +## main + +**一 = geometry_v1.area()** + +**二 = geometry_v2.area()** + +> 打印(一) + +> 打印(二) diff --git a/examples/packages-multi-version/marqdo.yaml b/examples/packages-multi-version/marqdo.yaml new file mode 100644 index 0000000..2c49d62 --- /dev/null +++ b/examples/packages-multi-version/marqdo.yaml @@ -0,0 +1,8 @@ +project: + name: multi-version + version: 0.1.0 +dependencies: + geometry_v1: + path: ./packages/geometry-v1 + geometry_v2: + path: ./packages/geometry-v2 diff --git a/examples/packages-multi-version/packages/geometry-v1/index.mq.md b/examples/packages-multi-version/packages/geometry-v1/index.mq.md new file mode 100644 index 0000000..94b7a62 --- /dev/null +++ b/examples/packages-multi-version/packages/geometry-v1/index.mq.md @@ -0,0 +1,3 @@ +## area + +*1* diff --git a/examples/packages-multi-version/packages/geometry-v1/marqdo.yaml b/examples/packages-multi-version/packages/geometry-v1/marqdo.yaml new file mode 100644 index 0000000..9a7c367 --- /dev/null +++ b/examples/packages-multi-version/packages/geometry-v1/marqdo.yaml @@ -0,0 +1,3 @@ +project: + name: geometry + version: 1.0.0 diff --git a/examples/packages-multi-version/packages/geometry-v2/index.mq.md b/examples/packages-multi-version/packages/geometry-v2/index.mq.md new file mode 100644 index 0000000..39725d2 --- /dev/null +++ b/examples/packages-multi-version/packages/geometry-v2/index.mq.md @@ -0,0 +1,3 @@ +## area + +*2* diff --git a/examples/packages-multi-version/packages/geometry-v2/marqdo.yaml b/examples/packages-multi-version/packages/geometry-v2/marqdo.yaml new file mode 100644 index 0000000..11685ec --- /dev/null +++ b/examples/packages-multi-version/packages/geometry-v2/marqdo.yaml @@ -0,0 +1,3 @@ +project: + name: geometry + version: 2.0.0 diff --git a/examples/plugin-multi-export/README.md b/examples/plugin-multi-export/README.md new file mode 100644 index 0000000..c1db83f --- /dev/null +++ b/examples/plugin-multi-export/README.md @@ -0,0 +1,17 @@ +# Multi-export plugin example + +One native library exports two complete names: `solver.add` and `solver.neg`. +Both are registered and callable; there is no "first prefix wins" namespace. + +```sh +./examples/plugin-multi-export/build.sh +marqdo check examples/plugin-multi-export/plugin-call.mq.md \ + --plugin examples/plugin-multi-export +marqdo run examples/plugin-multi-export/plugin-call.mq.md \ + --plugin examples/plugin-multi-export \ + --trust-native-plugin --allow-plugin demo.solver +``` + +`check --plugin` validates both signatures without loading the library. The +runtime still requires the explicit in-process trust decision; a C ABI is not a +sandbox, and an isolated worker transport is not part of this build. diff --git a/examples/plugin-multi-export/build.sh b/examples/plugin-multi-export/build.sh new file mode 100755 index 0000000..1700189 --- /dev/null +++ b/examples/plugin-multi-export/build.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +set -euo pipefail +here="$(cd "$(dirname "$0")" && pwd)" +repo="$(cd "$here/../.." && pwd)" +cd "$repo" +cc -std=c11 -O2 -shared -fPIC -I include -DMQ_SOLVER_MULTI_EXPORT \ + -o "$here/solver.so" examples/plugin-demo/solver.c +hash="$(sha256sum "$here/solver.so" | cut -d' ' -f1)" +python3 - "$here/plugin.yaml" "$hash" <<'PY' +import pathlib, re, sys +path, digest = sys.argv[1], sys.argv[2] +p = pathlib.Path(path) +text = p.read_text() +text = re.sub(r'(?m)^(\s*sha256:\s*")[0-9a-fA-F]{64}(")', r'\g<1>' + digest + r'\g<2>', text) +p.write_text(text) +PY +echo "built $here/solver.so" diff --git a/examples/plugin-multi-export/plugin-call.mq.md b/examples/plugin-multi-export/plugin-call.mq.md new file mode 100644 index 0000000..975fd35 --- /dev/null +++ b/examples/plugin-multi-export/plugin-call.mq.md @@ -0,0 +1,9 @@ +## main + +**和 = solver.add(a=20, b=22)** + +**相反数 = solver.neg(a=7)** + +> 打印(和) + +> 打印(相反数) diff --git a/examples/plugin-multi-export/plugin.yaml b/examples/plugin-multi-export/plugin.yaml new file mode 100644 index 0000000..c380be4 --- /dev/null +++ b/examples/plugin-multi-export/plugin.yaml @@ -0,0 +1,18 @@ +# Two exports under different prefixes, built from the shared C demo with +# -DMQ_SOLVER_MULTI_EXPORT. Installing grants nothing; loading requires trust. +plugin: + name: demo.solver + version: 0.1.0 + abi: "^1.0" + kind: native + exports: + - name: solver.add + signature: "($a: Int, $b: Int) -> Int" + - name: solver.neg + signature: "($a: Int) -> Int" + requires: + - math.compute + artifacts: + - target: x86_64-unknown-linux-gnu + file: solver.so + sha256: "0000000000000000000000000000000000000000000000000000000000000000" diff --git a/examples/tool-unknown-name/README.md b/examples/tool-unknown-name/README.md new file mode 100644 index 0000000..99147e7 --- /dev/null +++ b/examples/tool-unknown-name/README.md @@ -0,0 +1,19 @@ +# Unknown-name CLI tool example + +This directory is a complete Tool Protocol v1 package. Nothing named +`benchmark` exists in the Marqdo CLI source; after installation the unknown +top-level command is dispatched by the registry. + +```sh +marqdo tool install examples/tool-unknown-name/tool.json +marqdo tool list +marqdo benchmark run . --some-tool-option +marqdo tool remove benchmark +``` + +The executable receives the remaining arguments verbatim, inherits stdio/cwd, +and its exit code is propagated. `MARQDO_TOOL_PROTOCOL=1` and `MARQDO_BIN` are +provided for tools that need `check --emit`/`run --trace-file`. + +A Tool is a user-run native process. It is **not** a C ABI plugin, a foreign +kernel, or a program inside the `.mq.md` sandbox. diff --git a/examples/tool-unknown-name/bin/marqdo-benchmark b/examples/tool-unknown-name/bin/marqdo-benchmark new file mode 100755 index 0000000..ce08edc --- /dev/null +++ b/examples/tool-unknown-name/bin/marqdo-benchmark @@ -0,0 +1,8 @@ +#!/bin/sh +# A deliberately tool-specific program: the Marqdo CLI knows no `benchmark` +# command or its options. +printf 'benchmark tool: protocol=%s\n' "${MARQDO_TOOL_PROTOCOL:-unset}" +for argument in "$@"; do + printf 'arg=%s\n' "$argument" +done +exit 0 diff --git a/examples/tool-unknown-name/tool.json b/examples/tool-unknown-name/tool.json new file mode 100644 index 0000000..8efb8c8 --- /dev/null +++ b/examples/tool-unknown-name/tool.json @@ -0,0 +1,11 @@ +{ + "schema": "marqdo.cli-tool", + "schema_version": 1, + "name": "demo.benchmark", + "version": "0.1.0", + "command": "benchmark", + "entrypoint": "bin/marqdo-benchmark", + "compatibility": { + "marqdo": ">=0.1,<1" + } +} diff --git a/spec/schemas/analysis-v1.schema.json b/spec/schemas/analysis-v1.schema.json new file mode 100644 index 0000000..854a86f --- /dev/null +++ b/spec/schemas/analysis-v1.schema.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://marqdo.dev/schemas/analysis-v1.schema.json", + "title": "Marqdo Analysis v1", + "type": "object", + "required": ["schema", "schema_version", "producer", "project", "modules", "diagnostics"], + "properties": { + "schema": {"const": "marqdo.analysis"}, + "schema_version": {"const": 1}, + "producer": { + "type": "object", + "required": ["name", "version", "markdown_profile"], + "properties": { + "name": {"type": "string"}, + "version": {"type": "string"}, + "markdown_profile": {"const": "marqdo.md.v1"} + }, + "additionalProperties": true + }, + "project": { + "type": "object", + "required": ["root_id", "lock_digest"], + "properties": { + "root_id": {"type": "string"}, + "lock_digest": {"type": "string"} + }, + "additionalProperties": true + }, + "modules": { + "type": "array", + "items": { + "type": "object", + "required": ["id", "package_instance_id", "relative_path", "source_digest", "units", "functions", "imports", "references", "calls"], + "properties": { + "id": {"type": "string", "pattern": "::"}, + "package_instance_id": {"type": "string"}, + "relative_path": {"type": "string"}, + "source_digest": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, + "units": {"type": "array"}, + "functions": {"type": "array"}, + "imports": {"type": "array"}, + "references": {"type": "array"}, + "calls": {"type": "array"}, + "resources": {"type": "integer", "minimum": 0} + }, + "additionalProperties": true + } + }, + "diagnostics": {"type": "array"} + }, + "additionalProperties": true +} diff --git a/spec/schemas/tool-v1.schema.json b/spec/schemas/tool-v1.schema.json new file mode 100644 index 0000000..ea3845f --- /dev/null +++ b/spec/schemas/tool-v1.schema.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://marqdo.dev/schemas/tool-v1.schema.json", + "title": "Marqdo CLI Tool Manifest v1", + "type": "object", + "required": ["schema", "schema_version", "name", "version", "command", "entrypoint"], + "properties": { + "schema": {"const": "marqdo.cli-tool"}, + "schema_version": {"const": 1}, + "name": {"type": "string", "minLength": 1}, + "version": {"type": "string", "minLength": 1}, + "command": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"}, + "entrypoint": {"type": "string", "minLength": 1}, + "compatibility": { + "type": "object", + "properties": { + "marqdo": {"type": "string"}, + "analysis": {"type": "array", "items": {"type": "integer", "minimum": 1}}, + "trace": {"type": "array", "items": {"type": "integer", "minimum": 1}} + }, + "additionalProperties": true + } + }, + "additionalProperties": true +} diff --git a/spec/schemas/trace-v1.schema.json b/spec/schemas/trace-v1.schema.json new file mode 100644 index 0000000..63da3a5 --- /dev/null +++ b/spec/schemas/trace-v1.schema.json @@ -0,0 +1,55 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://marqdo.dev/schemas/trace-v1.schema.json", + "title": "Marqdo Trace v1", + "type": "object", + "required": ["schema", "schema_version", "run", "source", "events"], + "properties": { + "schema": {"const": "marqdo.trace"}, + "schema_version": {"const": 1}, + "run": { + "type": "object", + "required": ["id", "entry", "status"], + "properties": { + "id": {"type": "string"}, + "entry": {"type": "string"}, + "status": {"type": "string"} + }, + "additionalProperties": true + }, + "source": { + "type": "object", + "required": ["root_id", "analysis_digest"], + "properties": { + "root_id": {"type": "string"}, + "analysis_digest": {"type": "string"} + }, + "additionalProperties": true + }, + "events": { + "type": "array", + "items": { + "type": "object", + "required": ["seq", "kind"], + "properties": { + "seq": {"type": "integer", "minimum": 0}, + "kind": {"type": "string"}, + "function_id": {"type": ["string", "null"]}, + "module": {"type": ["string", "null"]}, + "span": { + "type": ["object", "null"], + "properties": { + "start": {"type": "integer", "minimum": 0}, + "end": {"type": "integer", "minimum": 0} + } + }, + "detail": {"type": ["string", "null"]}, + "operation": {"type": "string"}, + "duration_micros": {"type": "integer", "minimum": 0} + }, + "additionalProperties": true + } + } + }, + "additionalProperties": true +}