release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
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

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.
This commit is contained in:
cflmy committed 2026-11-22 02:31:32 +08:00
1 parent 56189b176c
commit 2c7c4f31e7
55 files changed
+3136 -453

No files matched your search

+119
View File
@@ -0,0 +1,119 @@
# 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`](../../spec/tool-v1.md)
(implemented and frozen for protocol v1).
## 1. Package layout
```text
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:
```json
{
"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
```bash
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):
```bash
"$MARQDO_BIN" check index.mq.md --refs --emit ./analysis.json
```
Dynamic input:
```bash
"$MARQDO_BIN" run index.mq.md --trace-file ./trace.json
```
See [analysis-trace.md](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.