Skip to content

feat(release): add synchronized macOS arm64 CLI artifact #3002

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
zupengwang wants to merge 4 commits into from
Closed

feat(release): add synchronized macOS arm64 CLI artifact #3002

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
519c06c
feat(release): add synchronized macOS CLI artifact
zupengwang Aug 14, 2026
12bc413
fix(release): include eval runtime assets
zupengwang Aug 15, 2026
8bef77d
fix(release): enforce pinned npm toolchain
zupengwang Aug 15, 2026
083d006
test(release): follow dependency patch versions
zupengwang Aug 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 63 additions & 28 deletions .github/RELEASE_CHECKLIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,85 @@
# Desktop release checklist
# Product release checklist

The `Release desktop` workflow is the single release entry point. It packages, verifies, and creates one draft GitHub Release carrying the Apple Silicon macOS and Windows x64 builds; it never publishes the release. The macOS build is signed, notarized, and stapled. The Windows build is unsigned.
The `Release` workflow is Maka's single release entry point. Desktop, CLI/TUI, and source
materials share one source commit, root product version, tag, GitHub Release, Draft decision,
and release gate. The workflow creates no Draft until every required artifact job succeeds.

Phase 1 requires:

- signed and notarized Apple Silicon macOS Desktop artifacts;
- the unsigned Windows x64 Desktop installer and ZIP;
- the signed, notarized, relocatable Apple Silicon CLI/TUI ZIP;
- bundled Git source materials;
- checksums generated after each artifact reaches its final form.

## One-time repository setup

Create a GitHub Environment named `release`. Add required reviewers if the repository needs a release approval gate, then configure these environment secrets:
Create a protected GitHub Environment named `release`, require the appropriate reviewers, and
configure:

- `CSC_LINK`: base64-encoded Developer ID Application `.p12`;
- `CSC_KEY_PASSWORD`: password for that `.p12`;
- `APPLE_API_KEY`: raw contents of an App Store Connect API `.p8` key;
- `APPLE_API_KEY_ID`: App Store Connect API key ID;
- `APPLE_API_ISSUER`: App Store Connect API issuer ID.

Windows needs no secrets while the build is unsigned: electron-builder skips signing when no certificate is configured. Adding an Authenticode certificate later means configuring it in `apps/desktop/electron-builder.config.mjs`, and nothing else: electron-builder derives the publisher name that authenticates updates from the certificate itself.
Windows remains unsigned until an Authenticode policy and certificate are added. Release secrets
must never be exposed to fork or ordinary pull-request jobs.

## Create the draft
## Create the complete Draft

1. Confirm the intended commit is on `main`, CI is green, and `apps/desktop/package.json` contains a version that has never been released.
2. In GitHub Actions, run `Release desktop` against `main`.
3. Confirm every workflow step passes on both platforms and a draft release named `v<version>` exists.
4. Confirm the draft records the intended commit SHA and contains the macOS DMG, ZIP, `latest-mac.yml`, the Windows `.exe`, ZIP, `latest.yml`, the bundled Git source-materials archive, and matching `.sha256` files.
5. Extract the bundled Git source-materials archive. Confirm `SOURCE_MANIFEST.json` and `README.txt` are present, every manifest archive is present, and the manifest pins the expected Dugite native release.
6. Confirm the packaged applications contain `licenses/git/LICENSE.txt`, `NOTICE.txt`, and `SOURCE_OFFER.txt`.
1. Confirm the intended commit is on `main`, required CI is green, and root `package.json`
contains a product version that has never been released.
2. Confirm `apps/desktop/package.json` and `packages/cli/package.json` exactly match the root
version, and the CLI manifest exposes only the `maka` command.
Comment on lines +33 to +34

@coderabbitai coderabbitai Bot Aug 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Show the CLI bin declarations and any maka-agent references.
rg -n '"bin"' -A6 packages/cli/package.json
rg -n 'maka-agent' --glob '!node_modules' -C2

Repository: maka-agent/maka-agent

Length of output: 432

🏁 Script executed:

#!/bin/bash
printf '%s\n' '--- packages/cli/package.json ---'
cat -n packages/cli/package.json | sed -n '1,45p'
printf '%s\n' '--- release checklist ---'
cat -n .github/RELEASE_CHECKLIST.md | sed -n '25,50p'
printf '%s\n' '--- issue and agent references ---'
rg -n '1510|maka-agent|maka-agent' .github README.md packages apps --glob '!node_modules' -C2 || true
printf '%s\n' '--- repository metadata ---'
git remote -v

Repository: maka-agent/maka-agent

Length of output: 50379

🌐 Web query:

site:github.com/maka-agent/maka-agent/issues/1510 maka-agent TUI launches through maka or maka-agent

💡 Result:

Issue #1510 requests a standalone macOS arm64 CLI/TUI artifact containing the maka command. It should launch the TUI when invoked as either maka or maka-agent, while also supporting run, eval, and inspect. (github.com)

Citations:

Align the CLI contract with issue #1510

Issue #1510 requires the TUI to launch as both maka and maka-agent, but packages/cli/package.json exposes only maka, and CLI tests reject maka-agent. Update the manifest, tests, and checklist, or document the intentional removal in issue #1510 and the PR.

3. In GitHub Actions, run `Release` against `main`.
4. Confirm `release-identity`, both Desktop matrix entries, `cli-macos-arm64`, `source`, and
`publish` pass. A skipped or failed required job must prevent Draft creation.
5. Confirm one Draft named `v<version>` targets the intended source SHA and contains at least:
- `Maka-<version>-mac-arm64.dmg` and checksum;
- `Maka-<version>-win-x64.exe` and checksum;
- `Maka-<version>-cli-mac-arm64.zip` and checksum;
- `Maka-<version>-bundled-git-source.tar.gz` and checksum;
- the platform update metadata and Desktop ZIPs produced by electron-builder.
6. Inspect the CLI ZIP. It must contain `bin/maka`, `RELEASE.json`, `LICENSE`, `NOTICE`,
`THIRD_PARTY_NOTICES.txt`, the pinned Node license, and no `bin/maka-agent`.
7. Confirm `RELEASE.json` records the Draft's product version and source SHA, the official Node
URL/archive/digest, npm version, workspace and production dependency closures, dependency
patches, Mach-O inventory, and `developer-id-notarized` signing state.
8. Extract the bundled Git source-materials archive. Confirm `SOURCE_MANIFEST.json`, `README.txt`,
all manifest archives, and the expected Dugite native release are present.

## Acceptance on another Apple Silicon Mac

Download the DMG and its `.sha256` file through the GitHub UI. This download path applies the real browser quarantine metadata that CI intentionally does not simulate.
Download the DMG, CLI ZIP, and their checksum files through a browser from the Draft. Do not move
artifacts directly from the workflow runner; the browser path supplies the real quarantine
boundary.

1. From the download directory, run `shasum -a 256 -c Maka-<version>-mac-arm64.dmg.sha256`.
2. Open the DMG in Finder, drag Maka to Applications, and launch it from Finder.
3. Confirm macOS opens Maka without an unidentified-developer or damaged-app warning.
4. Run `spctl --assess --type execute --verbose=4 /Applications/Maka.app` and confirm it is accepted with a Developer ID origin.
5. Configure a model connection, send one basic prompt, and run one representative file-tool task.
6. Install `ripgrep` with `brew install ripgrep`, then confirm a task using `Grep` works.
7. Confirm the known limitation is accurate: Computer Use is not included.
1. Run `shasum -a 256 -c` for the DMG and CLI ZIP.
2. Install and launch the Desktop app from Finder. Confirm there is no unidentified-developer or
damaged-app warning.
3. Run `spctl --assess --type execute --verbose=4 /Applications/Maka.app` and confirm a Developer
ID origin.
4. Extract the CLI ZIP without clearing quarantine. Run `bin/maka --version` and `bin/maka --help`.
5. Create an external link, for example `ln -s "$PWD/bin/maka" /tmp/maka-release-acceptance`, and
confirm the linked command reports the same version and help output.
6. Start `maka` with no arguments and confirm the TUI renders, accepts input, and exits cleanly.
7. Exercise one non-interactive `maka run`, one deterministic `maka eval`, and one streaming
tool-call path against the packaged artifact.
Comment on lines +63 to +68

@coderabbitai coderabbitai Bot Aug 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Make the invocation path consistent in steps 4, 6, and 7.

Step 4 uses bin/maka --version. Step 6 says "Start maka", and step 7 says maka run and maka eval. The artifact is relocatable and is not on PATH after extraction. An operator following the text literally gets command not found.

Use bin/maka in steps 6 and 7, or add one explicit PATH line after step 4.

📝 Proposed wording fix 
-6. Start `maka` with no arguments and confirm the TUI renders, accepts input, and exits cleanly.
-7. Exercise one non-interactive `maka run`, one deterministic `maka eval`, and one streaming
+6. Start `bin/maka` with no arguments and confirm the TUI renders, accepts input, and exits cleanly.
+7. Exercise one non-interactive `bin/maka run`, one deterministic `bin/maka eval run`, and one streaming
    tool-call path against the packaged artifact.

8. Configure a Desktop model connection, send one prompt, and run one representative file-tool
task. Confirm the documented Computer Use limitation remains accurate.

## Acceptance on a Windows x64 machine

Download the `.exe` installer and its `.sha256` file through the GitHub UI. The build is unsigned, so this pass is about confirming the expected warnings and that the app still runs.
Download the installer and checksum through a browser from the same Draft.

1. From the download directory, run `Get-FileHash Maka-<version>-win-x64.exe -Algorithm SHA256` in PowerShell and confirm the hash matches the `.sha256` file.
2. Run the installer. Confirm SmartScreen shows the expected unrecognized-publisher warning, and that continuing through **More info → Run anyway** completes the install.
3. Launch Maka from the Start menu.
4. Configure a model connection, send one basic prompt, and run one representative file-tool task.
5. Install `ripgrep` with `winget install BurntSushi.ripgrep.MSVC`, restart Maka so the new `PATH` applies, then confirm a task using `Grep` works.
6. Run one terminal task and confirm the shell integration works against the packaged `node-pty`.
7. Confirm the known limitation is accurate: Computer Use is not included.
1. Verify the SHA-256 in PowerShell.
2. Run the installer and confirm the expected unsigned-publisher SmartScreen flow.
3. Launch Maka from the Start menu, configure a model connection, send one prompt, and run one
representative file-tool task.
4. Run one terminal task and confirm packaged `node-pty` behavior.
5. Confirm the documented Computer Use limitation remains accurate.

Publish the draft only after all checks pass on both platforms. If acceptance fails, keep the draft unpublished, fix the issue, increment the desktop version, and run the workflow again; do not replace an existing release identity.
Publish only after both independent-machine acceptance passes. If any required artifact or
acceptance step fails, keep the Draft unpublished, fix the issue, increment the root product
version, and run the full workflow again. Never replace an existing release identity.
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ jobs:
- run: npm run lint
- run: npm run format:check
- run: npm run build
- name: Release contract tests
run: npm run test:release
Comment on lines +60 to +61

@coderabbitai coderabbitai Bot Aug 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Show the changes job and its path filters.
sed -n '1,60p' .github/workflows/ci.yml
fd -H -t f -g '*.y*ml' .github | xargs rg -n 'filters|paths|scripts/' -C2
rg -n '"test:release"' package.json -A2

Repository: maka-agent/maka-agent

Length of output: 10624

🏁 Script executed:

#!/bin/bash
set -e
script="$(fd -H -t f 'ci-test-plan\.mjs$' . | head -n1)"
printf '%s\n' "== $script =="
ast-grep outline "$script"
printf '%s\n' '== filter definitions and release inputs =='
rg -n -C4 'code|scripts|package\.json|release|workflow|filter|paths' "$script"
printf '%s\n' '== relevant workflow and manifest references =='
rg -n -C2 'release|package\.json|scripts/' .github/workflows/release.yml .github/workflows/ci.yml package.json

Repository: maka-agent/maka-agent

Length of output: 34652

🏁 Script executed:

#!/bin/bash
set -e

printf '%s\n' '== planner implementation =='
sed -n '209,310p' scripts/ci-test-plan.mjs

printf '%s\n' '== planner tests and release-test coverage =='
rg -n -C3 'planTests|ci-test-plan|release\.yml|package\.json|scripts/' scripts --glob '*test*.mjs' --glob 'ci-test-plan.mjs'

printf '%s\n' '== deterministic path probe (source treated as data) =='
python3 - <<'PY'
from pathlib import Path
import json

source = Path("scripts/ci-test-plan.mjs").read_text()
root = json.loads(Path("package.json").read_text())

full_suite = set()
in_full = False
for line in source.splitlines():
    if line.startswith("const FULL_SUITE_FILES = new Set(["):
        in_full = True
        continue
    if in_full and line.strip() == "]);":
        break
    if in_full:
        value = line.strip().rstrip(",")
        if value.startswith("'") and value.endswith("'"):
            full_suite.add(value[1:-1])

workspace_dirs = set(root.get("workspaces", []))
typecheck_only = set()
in_typecheck = False
for line in source.splitlines():
    if line.startswith("const TYPECHECK_ONLY_FILES = new Set(["):
        in_typecheck = True
        continue
    if in_typecheck and line.strip() == "]);":
        break
    if in_typecheck:
        value = line.strip().rstrip(",")
        if value.startswith("'") and value.endswith("'"):
            typecheck_only.add(value[1:-1])

def code_for(path):
    if path in full_suite:
        return True
    if path in workspace_dirs or any(path.startswith(d + "/") for d in workspace_dirs):
        return True
    if path.startswith("scripts/"):
        return True
    if path.startswith("skills/"):
        return True
    if path in typecheck_only:
        return True
    if path.startswith(".github/"):
        return False
    return True

cases = {
    "scripts/release-identity.mjs": True,
    "scripts/release.test.mjs": True,
    "package.json": True,
    ".github/workflows/ci.yml": True,
    ".github/workflows/release.yml": False,
}
for path, expected in cases.items():
    actual = code_for(path)
    print(f"{path}: code={str(actual).lower()} expected={str(expected).lower()}")
    assert actual == expected, (path, actual, expected)

assert "package.json" in full_suite
assert ".github/workflows/release.yml" not in full_suite
print("planner path assertions passed")
PY

Repository: maka-agent/maka-agent

Length of output: 16198

Include .github/workflows/release.yml in the code selection.

Changes to release scripts and package.json run npm run test:release, but release-workflow-only changes do not.

- run: npm run typecheck
# Generated-artifact governance. astryx-theme/maka.{css,js} are built
# from makaTheme.ts, which is now the renderer's type-scale authority —
Expand Down
263 changes: 0 additions & 263 deletions .github/workflows/release-desktop.yml
View file
Open in desktop

This file was deleted.

Loading