# `@markdown-ai/cli` — reference implementation specification > **Status:** Implemented reference CLI (v1.0.0-rc.3; implementation continues to mature toward v1.0.0) > **Audience:** Implementers of the MDA reference CLI and of independent compatible compilers/validators. > **Spec dependency:** [`spec/v1.0/`](../../spec/v1.0/) is normative. This document is informative architecture for the reference implementation. The reference implementation is published as `@markdown-ai/cli` on npm, written in TypeScript, and lives in this directory tree (`apps/cli/`). It is the only package the spec endorses. Independent implementations are welcome and held to the same conformance suite. --- ## 1. Scope What `@markdown-ai/cli` MUST do at v1.0.0: - **Parse** a `.mda` source file: extract YAML frontmatter, body, footnote-encoded relationships. - **Validate** any `.mda` source against `schemas/frontmatter-source.schema.json`. - **Validate** any `.md` output against the relevant target schema (`SKILL.md`, `AGENTS.md`, `MCP-SERVER.md`). - **Compile** a `.mda` source into one or more conformant `.md` outputs per the target schemas, with field relocation per [`spec/v1.0/01-source-and-output.md §01-4`](../../spec/v1.0/01-source-and-output.md). - **Canonicalize** any artifact for integrity computation (JCS-based per [`spec/v1.0/08-integrity.md`](../../spec/v1.0/08-integrity.md)). - **Verify** signatures and integrity against an explicit operator-supplied policy. - **Sign** an artifact only through methods whose emitted metadata round-trips through the verifier. `did:web` can ship when fixtures pass; Sigstore signing remains unavailable or experimental until the JS implementation proves MDA-compatible DSSE/Rekor metadata. - **Run** the conformance suite at `conformance/` and report pass/fail per fixture. What `@markdown-ai/cli` MUST NOT do at v1.0.0: - Edit body prose for size budgets (the compiler is structural, not editorial). - Project vendor namespaces into sibling files (cut from v1.0). - Interpret unknown vendor namespaces beyond preserving them verbatim. - Trust package-default signing identities or verification policy. - Sign as part of `mda compile`; signing is a separate explicit operation. --- ## 2. CLI surface ``` mda # print full help mda --help # print full help mda init [--out ] [--json] # scaffold a .mda source mda validate [--target T|auto] [--json] # source or output mda compile --target T... [--out-dir ] [--integrity] [--json] mda canonicalize [--target T|auto] [--sidecar ] [--json] mda integrity compute [--target T|auto] [--sidecar ] [--algorithm A] [--json] mda integrity verify [--target T|auto] [--sidecar ] [--json] mda sign --method did-web --key --identity (--out |--in-place) [--json] mda verify --policy [--target T|auto] [--sidecar ] [--json] mda conformance [--suite ] [--level V|C] [--json] ``` `T` is one of `source`, `SKILL.md`, `AGENTS.md`, or `MCP-SERVER.md`. Auto-detection is exact: `.mda` means `source`; known target basenames mean their target; any other `.md` path is a usage error unless `--target` is explicit. `MCP-SERVER.md` is a multi-file artifact. Commands that canonicalize, compute integrity, verify integrity, or verify trust for that target require `--sidecar `; the CLI must not guess the sidecar path. `validate MCP-SERVER.md` validates only the Markdown artifact and does not require or guess a sidecar. Every subcommand: - Returns exit 0 on success, non-zero on failure. - Emits machine-readable output (JSON) under `--json`. - Honors `--quiet` and `--verbose`. Running `mda` with no arguments is not an error. It prints the same full help as `mda --help`, including every command, every global flag, every command-specific option, required markers, short workflow examples, and exit-code meanings. It must not perform validation, compilation, signing, verification, network access, or file writes. `mda init ` prints a minimal valid `.mda` scaffold to stdout. `--out ` writes that scaffold atomically and refuses to overwrite an existing file. With `--json`, stdout is only JSON and includes `name`, `scaffold`, `out`, and `written`. `mda compile` writes to `--out-dir` when provided and to the current working directory when omitted. It refuses to overwrite existing output files and reports every planned and written output path in JSON mode. With `--json`, stdout contains only JSON. All JSON results include `ok`, `command`, `exitCode`, and `diagnostics`; artifact-reading commands also include the resolved `target`. `canonicalize --json` returns `canonicalBytesBase64`, `byteLength`, `target`, and `files`; raw canonical bytes are written to stdout only when `--json` is absent. `mda verify` requires `--policy `. The MVP CLI has no stable offline verification flag; policy-only matching must never count as cryptographic signature verification. --- ## 3. Module layout (planned) ``` apps/cli/ ├── src/ │ ├── parse/ # frontmatter + body + footnote extraction │ ├── schema/ # ajv loader, registry of target schemas │ ├── compile/ # source → outputs (per §01-4 + §06-targets/*) │ ├── canonical/ # JCS-based canonicalizer (§08) │ ├── integrity/ # compute + verify (§08) │ ├── sign/ # sigstore + did:web (§09) │ ├── verify/ # signature verification + policy │ ├── conformance/ # manifest runner, fixture executor │ └── cli/ # commander/citty wiring ├── package.json ├── tsconfig.json └── README.md ``` --- ## 4. Conformance levels The reference implementation declares only the conformance level it currently passes. It may claim **level C** ([`spec/v1.0/07-conformance.md §07-2.2`](../../spec/v1.0/07-conformance.md)) only after `mda conformance --suite conformance --level C` exits `0` against every required fixture in `conformance/manifest.yaml`. Level-V-only implementations (validators that do not compile) are conformant if they pass every `valid/` and `invalid/` fixture. --- ## 5. Release model Per [`SPEC.md`](../../SPEC.md) and [`spec/v1.0/00-overview.md §0.9`](../../spec/v1.0/00-overview.md): - `v1.0.0-rc.1` — spec freeze. Reference implementation passes the source-side and minimal output-side fixtures. - `v1.0.0-rc.N` — reference implementation maturity. Each rc adds capability and fixture coverage but does NOT change the spec. - `v1.0.0` — ships when the reference implementation passes 100% of the conformance suite at level C. The implementation MAY ship before `v1.0.0` final under the rc tag; users opt in. --- ## 6. Dependencies (planned) | Concern | Library | Notes | | ------- | ------- | ----- | | YAML parse / dump | `yaml` (`eemeli/yaml`) | YAML 1.2; preserves quoting; round-trip-safe. | | JSON Schema validator | `ajv` 8 + `ajv-formats` | Already in use by `scripts/validate-conformance.mjs`. | | JCS canonicalization | `@truestamp/canonify` | RFC 8785. | | Sigstore client | TBD | Add only after proving DSSE/Rekor metadata compatibility. | | did:web fetcher | `node:fetch` + `node:crypto` | No third-party dep. | | CLI framework | `commander` | Stable subcommand API; sufficient for v1.0. | All deps MUST be Apache-2.0 / MIT / BSD / ISC compatible. --- ## 7. Compatibility tests In addition to the MDA conformance suite, the implementation SHOULD pass the upstream `skills-ref validate` reference checker for every emitted `SKILL.md` (https://github.com/agentskills/agentskills/tree/main/skills-ref). When the two checkers disagree, the divergence MUST be tracked as an issue and resolved before the next spec patch. --- ## 8. What is explicitly out of scope for v1.0 - **Round-trip `.md` → `.mda` decompile.** Not part of v1.0. - **Sibling-file projection.** Cut from v1.0. - **Body editorial behavior** (auto-relocating prose into `references/`). - **TUF / The Update Framework** integration. Cut from v1.0. - **Provenance graphs / SLSA-style attestations** beyond what `signatures[]` already provides. Cut from v1.0. - **Custom hash algorithms** beyond sha256/384/512. - **Compound SemVer ranges** beyond exact + caret. These remain candidates for future minors (`v1.1+`) governed by the registry / RFC process described in [`REGISTRY.md`](../../REGISTRY.md). --- ## 9. Bootstrap status As of v1.0.0-rc.3, the TypeScript CLI is implemented under `src/` and publishes as `@markdown-ai/cli`. The legacy runner at [`scripts/validate-conformance.mjs`](../../scripts/validate-conformance.mjs) remains useful as an independent check, but `mda conformance` is the reference CLI entry point.