feat(release): distribute CLI/TUI for macOS arm64

[Astro-Han]

Problem

The current macOS arm64 release only distributes the Electron desktop DMG. Although the repository contains a working maka / maka-agent CLI whose default command launches the TUI, packages/cli and its internal workspace dependencies are private and no installable CLI/TUI artifact is attached to the GitHub Release.

Users who download Maka cannot use the CLI or TUI unless they clone the repository, install all development dependencies, and build the monorepo locally.

Desired outcome

Each version should be released from one source commit through one release workflow and one GitHub Release, while keeping the desktop and terminal products independently installable.

For the initial macOS arm64 scope, a release should contain:

• a signed and notarized Maka-<version>-mac-arm64.dmg for the desktop application;
• a standalone macOS arm64 CLI/TUI artifact containing the maka command;
• matching checksums for both artifacts.

The CLI artifact should:

• run without cloning the repository or installing its private workspace packages;
• launch the TUI when invoked as maka or maka-agent;
• support the existing non-interactive run, eval, and inspect commands;
• report the same version as the desktop release;
• remain usable without installing the desktop application.

The release workflow should build and verify both products before creating the draft release. Verification should cover at least maka --version, maka --help, TUI startup in a PTY, and one deterministic non-interactive command.

The standalone artifact should provide a stable source for a future Homebrew formula, while the desktop DMG can remain independently installable or be managed through a cask. Other operating systems and architectures can be added later.

Alternatives or workarounds

Today, contributors can run:

npm ci
npm run build
./node_modules/.bin/maka

This is a development workflow rather than a user-facing distribution path.

Bundling the CLI only inside Maka.app and exposing an “Install CLI” action would provide a single-download experience, but it would couple the CLI lifecycle to the desktop application and would not serve terminal-only or future cross-platform users cleanly.

Publishing the current workspace package directly to npm is also insufficient because its @maka/* dependencies are private; that would require either publishing the internal package graph or producing a self-contained CLI distribution.

[zupengwang]

Proposed CLI distribution contract

Based on the current unified release-desktop.yml boundary and the review of #1823, I propose that the first CLI release be a standalone, relocatable macOS arm64 ZIP with an embedded, exactly pinned Node runtime. A future project-owned Homebrew formula should consume this same immutable ZIP rather than define a second packaging format.

No release implementation should continue until this contract is agreed. After agreement, I will rebuild from current main and supersede #1823 instead of carrying forward its retired workflow wiring.

1. Artifact shape

Release asset:

Maka-<version>-cli-mac-arm64.zip

Stable layout:

Maka-<version>-cli-mac-arm64/
├── bin/maka
├── bin/maka-agent
├── libexec/node/bin/node
├── libexec/node_modules/...
├── libexec/packages/...
├── RELEASE.json
├── LICENSE
├── NOTICE
└── THIRD_PARTY_NOTICES.txt

bin/maka, bin/maka-agent, and the documented RELEASE.json fields are the public contract. libexec/** remains an implementation detail. Both launchers must remain relocatable and work when invoked through a symlink outside the archive root.

The tradeoff is a larger artifact, but it avoids system-Node drift, private-workspace installation problems, and native-addon incompatibility.

2. Initial platform matrix

Phase 1 ships only macOS arm64, matching the original issue scope and the currently validated native dependency closure.

Windows x64 CLI should be a later matrix entry after its native binaries, Authenticode policy, launcher, and real-machine acceptance path are defined. Other architectures can then be added without creating a new release boundary.

3. Version authority

For Phase 1, apps/desktop/package.json remains the release-version authority because the current workflow, tags, and release names already derive from it.

The CLI workspace version is not an independent release version. Packaging writes the product release version into staged CLI metadata, and maka --version and maka-agent --version must report it. The workflow should fail if the root and Desktop product versions drift.

4. Commit, tag, and release ownership

Desktop and CLI share:

• one dispatched source commit;
• one v<version> tag;
• one GitHub Release;
• one draft/publication decision.

The CLI has an independent packager and verifier, but not an independent release publisher.

5. Workflow and staging

Extend the current unified workflow boundary:

release-desktop.yml
├── build                         macOS and Windows Desktop artifacts
├── cli-macos-arm64               macOS CLI artifact
├── source                        bundled source materials
└── publish                       one draft GitHub Release

The CLI packager stages files under packages/cli/release/ and uploads an Actions artifact named release-cli-macos-arm64. It must not call gh release create.

The existing publish job downloads all release-* artifacts, verifies the expected checksums and release identity, and creates the single draft release.

6. Third-party notices

The CLI must have notices generated from the exact maka-agent production dependency closure rather than reuse the Desktop notice blindly.

The existing notice generator should be parameterized by workspace owner and output path. The ZIP contains the resulting THIRD_PARTY_NOTICES.txt, the Maka license and notice, and the embedded Node license. The verifier checks that these files are present and match the packaged dependency metadata.

7. Signing, notarization, checksum, and verification ownership

The cli-macos-arm64 job owns:

1. deriving and staging the workspace closure from package manifests;
2. applying repository dependency patches;
3. validating the pinned official Node runtime;
4. enumerating every Mach-O file in the staged artifact;
5. signing every Mach-O with the same Developer ID team;
6. creating and notarizing the final ZIP;
7. generating the checksum after the final artifact exists;
8. running the independent verifier.

The verifier must cover safe archive paths, exact architecture, no external Node libraries, workspace closure, no dangling symlinks or test output, signing identity, quarantine execution, aliases, help, deterministic eval, TUI startup, streaming tool calls, and invocation through an external symlink.

The publish job only validates and collects completed artifacts. Browser-download acceptance on a separate Apple Silicon Mac remains the human release gate.

Release credentials are available only in the protected upstream release environment and never in fork or ordinary PR jobs.

8. Homebrew compatibility

A future project-owned Homebrew formula should download the versioned ZIP and verify its published SHA-256.

The formula may install the complete archive tree into its private prefix and expose maka and maka-agent through symlinks. It must not depend on specific paths below libexec, which remain private.

Before calling the layout Homebrew-stable, acceptance must prove both commands work through symlinks outside the extracted archive.

Supply-chain boundaries

• release only from protected main;
• pin exact Node and npm inputs and verify Node provenance or the official archive digest;
• use the committed lockfile and apply every committed dependency patch;
• record source SHA, product version, toolchain versions, workspace closure, patch list, platform, architecture, and signing state in RELEASE.json;
• generate checksums after signing and notarization;
• keep the GitHub Release as Draft until separate-machine acceptance passes.

Proposed delivery

1. Agree on this contract in feat(release): distribute CLI/TUI for macOS arm64 #1510.
2. Create a clean implementation PR from current main, carrying forward only the independent packager, verifier, and behavior-level tests from feat(release): distribute standalone macOS arm64 CLI #1823.
3. Keep the CLI asset out of the GitHub Release until the protected signing and notarization path has run successfully.
4. Add the verified CLI artifact to the unified draft release.
5. Add a Homebrew tap and additional CLI platforms in follow-up work.

Please confirm or amend the eight decisions above. Until then, I will keep #1823 paused and will not rebase its old workflow wiring.

[Astro-Han]

Thanks for writing out the distribution contract. I agree with the overall direction: the CLI/TUI should be a first-class artifact of the same Maka product release, not a separate release line.

I would like to settle the contract with the following decisions and amendments:

1. Strong release synchronization. Desktop and CLI/TUI share one source commit, product version, tag, GitHub Release, draft/publication decision, and release gate. Every artifact declared required for that release must pass before the draft is created.

2. Product-level version authority. The root package.json is the sole product-version authority rather than apps/desktop/package.json. The Desktop and CLI manifests must match it, and the workflow fails before packaging if they drift. Tags, filenames, RELEASE.json, Desktop metadata, and maka --version all use that product version.

3. One terminal product and one command. The TUI is the default interactive mode of the CLI, not a separate artifact. The public command is maka; we will not publish a maka-agent command alias because there is no released compatibility requirement for it. The package or repository may still use maka-agent as an internal/distribution name.

4. Initial platform scope. Phase 1 ships the CLI/TUI only for macOS arm64. This is still a required artifact of the synchronized release. Windows CLI support is follow-up work and will join the same release workflow and version line when its native closure, launcher, signing policy, and real-machine acceptance path are ready.

5. Authoritative artifact. The initial CLI artifact is a signed, notarized, relocatable Maka-<version>-cli-mac-arm64.zip containing an exactly pinned official Node runtime and the real production workspace/npm dependency closure derived from manifests. We will not depend on a system Node installation or use a single-file bundling/SEA path. bin/maka and the documented RELEASE.json fields are public contract; libexec/** remains private.

6. Product-level release workflow. Rename the current Desktop-oriented workflow to release.yml and give it one release-identity job that resolves and validates the root version, tag, and source commit. Independent Desktop, CLI, and source jobs produce verified artifacts; one publish job only collects them and creates the single Draft Release.

7. Existing release gate remains authoritative. The current model is retained: build, sign, notarize, checksum, and verify in the protected release environment; create a complete Draft Release; then perform browser-download acceptance on separate Apple Silicon and Windows x64 machines before a human publishes it. The CLI adds its own Gatekeeper, external-symlink, TUI, non-interactive, and streaming tool-call acceptance coverage.

8. Installation channels do not define releases. The GitHub Release ZIP is the immutable distribution source. Homebrew and npm may be added afterward and must not block the initial CLI release or introduce another package layout, version authority, or release line.

Please rebuild the implementation from current main and supersede #1823. Carry forward the manifest-derived dependency closure, independent packager/verifier, signing and notarization work, and behavior-level verification. Do not carry forward the retired workflow wiring or the maka-agent launcher alias.

Disclosure: this comment was drafted with Codex and reviewed and approved by the human contributor.

简体中文

感谢你整理这份分发契约。我认可整体方向：CLI/TUI 应当是同一个 Maka 产品版本中的一等制品，而不是另一条独立发布线。

我希望按以下决定和修订确定最终契约：

1. 强同步发布。 Desktop 与 CLI/TUI 共享同一个源码提交、产品版本、Tag、GitHub Release、Draft/公开决定和发布闸门。该版本声明为必需的所有制品都必须通过，之后才能创建 Draft。

2. 产品级版本权威。 根目录 package.json 是唯一产品版本权威，而不是 apps/desktop/package.json。Desktop 和 CLI manifest 必须与其一致；如果发生漂移，workflow 应在打包前失败。Tag、文件名、RELEASE.json、Desktop 元数据和 maka --version 全部使用该产品版本。

3. 一个终端产品、一个命令。 TUI 是 CLI 的默认交互模式，不是独立制品。公开命令只有 maka；由于尚不存在已发布的兼容性要求，我们不会发布 maka-agent 命令别名。package 或仓库内部仍可继续使用 maka-agent 作为名称。

4. 首期平台范围。 第一阶段只为 macOS arm64 发布 CLI/TUI，但它仍是同步发布中的必需制品。Windows CLI 作为后续工作；在其原生依赖闭包、launcher、签名策略和真实机器验收路径准备完成后，加入同一个 release workflow 和版本线。

5. 权威制品。 首个 CLI 制品是经过签名、公证且可搬迁的 Maka-<version>-cli-mac-arm64.zip，其中包含精确锁定的官方 Node runtime，以及根据 manifests 推导出的真实 production workspace/npm 依赖闭包。我们不依赖系统 Node，也不采用单文件 bundling/SEA 路径。bin/maka 和有明确文档的 RELEASE.json 字段属于公开契约；libexec/** 保持为私有实现。

6. 产品级发布 workflow。 将当前以 Desktop 为中心的 workflow 重命名为 release.yml，并设置唯一的 release-identity job，用于解析和校验根版本、Tag 与源码提交。Desktop、CLI 和源码 job 分别生成并验证自己的制品；唯一的 publish job 只负责汇集制品并创建一个 Draft Release。

7. 继续沿用现有发布闸门。 保留当前模型：在受保护的 release environment 中构建、签名、公证、生成 checksum 并验证；创建包含完整资产的 Draft Release；然后分别在 Apple Silicon 和 Windows x64 异机上通过浏览器下载验收，最后由人工公开。CLI 额外覆盖 Gatekeeper、外部 symlink、TUI、非交互命令和 streaming tool-call 验收。

8. 安装渠道不定义发布。 GitHub Release ZIP 是不可变的分发来源。Homebrew 和 npm 可以后续加入，但不得阻塞首次 CLI 发布，也不得引入另一套包布局、版本权威或发布线。

请从当前 main 重新构建实现并取代 #1823。保留基于 manifest 推导依赖闭包、独立 packager/verifier、签名与公证，以及行为级验证；不要继承已经退役的 workflow 接线，也不要保留 maka-agent launcher alias。

披露：本评论由 Codex 起草，并经人类贡献者审阅和批准。