Files
marqdo-cli/docs/developers/tools.md
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

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]
  }
}
  • version is the tool's SemVer.
  • compatibility.marqdo is the core product range. A stable-only >=3.0.0,<4.0.0 does not match a beta core; opt in explicitly. The CLI rejects a mismatched range at install and dispatch time with a requires marqdo … diagnostic.
  • analysis/trace are declared only if the tool consumes them; the current core provides Analysis v2 and Trace v2.
  • command must 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).
  • entrypoint is 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 marqdo binary: hash it before/after the suite and fail if it changes.
  • Cover the negative paths: unknown schema major, incompatible marqdo range, 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 check source.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 and examples/tool-unknown-name/ as a runnable dispatch fixture.