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.
4.1 KiB
External tools: CLI Tool Protocol v1
The core does not contain view, knowledge, prove, lint or any other
product command. A tool is a separate executable registered by the user; the
CLI only dispatches unknown top-level commands to registered tools and never
scans PATH for a guessed name.
Normative contract: ../../spec/tool-v1.md
(implemented and frozen for protocol v1).
1. Package layout
marqdo-view/
README.md
tool.json
bin/marqdo-view # built artifact; not a core-source dependency
src/
tests/contract/
examples/
tool.json for the 3.0.0-beta.1 product line:
{
"schema": "marqdo.cli-tool",
"schema_version": 1,
"name": "marqdo-view",
"version": "0.1.0",
"command": "view",
"entrypoint": "bin/marqdo-view",
"compatibility": {
"marqdo": ">=3.0.0-beta.1,<4.0.0",
"analysis": [2],
"trace": [2]
}
}
versionis the tool's SemVer.compatibility.marqdois the core product range. A stable-only>=3.0.0,<4.0.0does not match a beta core; opt in explicitly. The CLI rejects a mismatched range at install and dispatch time with arequires marqdo …diagnostic.analysis/traceare declared only if the tool consumes them; the current core provides Analysis v2 and Trace v2.commandmust match^[a-z][a-z0-9-]*$and must not collide with a built-in command (init,run,call,check,inspect,fmt,plugin,add,remove,lock,sync,tool,help).entrypointis package-relative, must be a regular executable file, and the whole bundle is hashed (per-file SHA-256 plus a bundle digest) at install and re-verified before every dispatch.
2. Install, list, dispatch
marqdo tool install ./marqdo-view # directory containing tool.json
marqdo tool list
marqdo view --help # dispatched to your executable
marqdo view index.mq.md
marqdo tool remove view
The CLI preserves cwd, stdio, exit status and ordinary arguments (no shell
string interpolation). It does not interpret the tool's own subcommands or
--help.
The tool receives:
| Variable | Meaning |
|---|---|
MARQDO_BIN |
absolute path of the running marqdo executable |
MARQDO_TOOL_PROTOCOL |
1 |
MARQDO_PROTOCOL_ANALYSIS |
2 when Analysis v2 was negotiated |
MARQDO_PROTOCOL_TRACE |
2 when Trace v2 was negotiated |
Call $MARQDO_BIN with an argv array; do not assume marqdo is on PATH.
3. Consume the public protocols
Static input (View/Knowledge/Proof):
"$MARQDO_BIN" check index.mq.md --refs --emit ./analysis.json
Dynamic input:
"$MARQDO_BIN" run index.mq.md --trace-file ./trace.json
See analysis-trace.md for fields and digest rules. Do not
depend on inspect --ir: that JSON is not a frozen cross-repository protocol.
The view tool renders the original Markdown, not the Analysis JSON; the
Analysis is an index, not a replacement for the source text.
4. Security contract
A Tool is a normal process started by the user. It does not inherit the
pure/project/strict guarantees of the .mq.md programs it reads, and it
must never execute document content implicitly or inherit grants from it.
Checksums verify bundle integrity only; they are not publisher authentication.
5. Testing and shipping
- Test against a frozen
marqdobinary: hash it before/after the suite and fail if it changes. - Cover the negative paths: unknown schema major, incompatible
marqdorange, reserved command, traversal/symlink entrypoint, tampered bundle file, missing entrypoint, tool crash/exit-status propagation. - Match a real Analysis v2/Trace v2 schema (
spec/schemas/) and checksource.analysis_digest. - Include README, minimal example, supported CLI product range, protocol versions, platform matrix, reproducible artifact hashes and limitations.
- The archive ships
examples/tool-samples/{sample-view,sample-knowledge,sample-proof}as independent source examples andexamples/tool-unknown-name/as a runnable dispatch fixture.