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
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:
1 parent
56189b176c
commit
2c7c4f31e7
55 files changed
+3136
-453
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user