doc_id: cli-distribution title: “CLI/TUI convenience distribution contract” language: en source_language: en implementation_status: current document_status: current translation_status: source-only last_verified: 2026-09-04 owners:
Maka's Apache release is the IPMC-approved source archive on ASF distribution infrastructure. The CLI/TUI ZIP and Desktop installers are required convenience artifacts built from that exact source identity. Phase 1 publishes one signed and notarized Apple Silicon artifact:
Maka-<version>-cli-mac-arm64.zip
The ZIP contains an exactly pinned official Node runtime and the production workspace/npm dependency closure derived from repository manifests and package-lock.json. It does not use a system Node installation or a single-file/SEA build.
Only these surfaces are stable:
bin/maka, including invocation through a symlink outside the extracted archive;RELEASE.json fields below.libexec/** is private and may change between releases. There is no public maka-agent launcher. The TUI is the default interactive mode of maka, not a separate artifact.
RELEASE.json fields:
| Field | Meaning |
|---|---|
schemaVersion | Metadata schema version, initially 1 |
product | Product name, Maka |
version | Root package.json product version |
sourceCommit | Exact source commit shared by every release artifact |
platform / architecture | Artifact target, macos / arm64 |
publicCommands | Public command list; exactly ["maka"] in Phase 1 |
node | Official Node version, source URL, archive name, and archive SHA-256 |
npmVersion | Exact npm version used to materialize the production closure |
dependencyPatches | Sorted repository patches applied to the staged dependencies |
productionDependencies | Sorted external name@version production closure |
thirdPartyNoticesSha256 | Digest binding notices to this artifact |
workspacePackages | Sorted manifest-derived production workspace closure |
machOBinaries | Sorted paths of every Mach-O file that must be signed and verified |
signing | developer-id-notarized for release artifacts; development for local checks |
The CLI-specific THIRD_PARTY_NOTICES.txt must enumerate exactly the external production dependencies recorded in RELEASE.json. The archive also carries the repository's DISCLAIMER-WIP, LICENSE, NOTICE, and the pinned Node runtime license. The archive checksum is generated only after signing and notarization complete.
Every Mach-O file inside the archive is signed and the ZIP is submitted to Apple's notary service. ZIP files cannot carry a stapled notarization ticket, so the first Gatekeeper assessment on another Mac may require network access to retrieve the ticket from Apple. The embedded code signatures and published SHA-256 remain available for offline verification; do not describe the ZIP itself as stapled.
Root package.json is the sole version authority. Desktop and CLI manifests must match before packaging. Desktop, CLI/TUI, and source jobs build independently from one commit; one publish job collects their verified outputs and creates one Draft GitHub Release.
The GitHub Release ZIP is the standalone convenience distribution source. Its exact bytes are covered by a Sigstore provenance bundle signed with the protected Finalize workflow identity. npm keeps its installer-specific tarball, OIDC, staged-publishing, and 2FA approval flow, but may start only after the product v<version> tag and GitHub Release exist. It checks out that tag's exact commit and derives the same version, runtime closure, file policy, notices, and source identity. It does not create a tag or GitHub Release and does not block creation of the product Draft. Homebrew must consume the standalone ZIP.
| Question | Decision | Enforced by |
|---|---|---|
| Which file owns the product version? | Root package.json; Desktop and CLI manifests must match it. | product-release-identity.mjs and release contract tests |
| Which event defines the Apache release? | The approved source archive and vote result. The v<version> tag and Draft GitHub Release identify convenience distributions built from that source commit. | ASF source-release workflow plus release.yml identity and exact-tag checks |
| Which convenience artifacts are required? | macOS, Windows, and Linux Desktop installers and update assets plus the macOS arm64 standalone CLI ZIP. | The exact manifest from product-release-identity.mjs, enforced by each artifact job and the publish job |
| Is npm another release authority? | No. It is an optional install channel whose Stage ref, source, workflow identity, and provenance all resolve to the existing product tag commit. | Tag-dispatched OIDC staging and read-only finalization; no npm-specific tag or GitHub Release |
| Does the standalone CLI define another package policy? | No. It derives the workspace closure, third-party pruning, notices, and Eval runtime assets from their current manifests and shared policy. | Packaging and artifact contract tests |
| Which commands are public? | maka only; TUI is its default mode. | CLI manifest, help tests, wrapper, and release metadata |