feat(release): distribute standalone macOS arm64 CLI

.github/RELEASE_CHECKLIST.md

@@ -17,7 +17,7 @@ Create a GitHub Environment named `release`. Add required reviewers if the repos
 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 macOS arm64` against `main`.
 3. Confirm every workflow step passes and a draft release named `v<version>` exists.
-4. Confirm the draft records the intended commit SHA and contains the DMG, its `.sha256` file, the ZIP, and `latest-mac.yml`.
+4. Confirm the draft records the intended commit SHA and contains the DMG, signed and notarized CLI/TUI ZIP, both `.sha256` files, the desktop ZIP, and `latest-mac.yml`.
 
 ## Acceptance on another Apple Silicon Mac
 
@@ -31,4 +31,15 @@ Download the DMG and its `.sha256` file through the GitHub UI. This download pat
 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.
 
+## CLI/TUI acceptance on another Apple Silicon Mac
+
+Download `Maka-<version>-cli-mac-arm64.zip` and its `.sha256` file through the GitHub UI. This browser-download path applies quarantine metadata and must exercise the signed native addons.
+
+1. Run `shasum -a 256 -c Maka-<version>-cli-mac-arm64.zip.sha256`.
+2. Extract the ZIP and add its `bin` directory to `PATH` without installing the desktop app.
+3. Confirm `maka --version` matches the desktop version and `maka-agent --version` reports the same value.
+4. Confirm `maka --help` lists `run`, `eval`, and `inspect`.
+5. Run `maka`, complete or cancel the first-run setup, and confirm the TUI renders correctly.
+6. Run one representative non-interactive command and confirm it completes without a repository checkout or system Node.js installation.
+
 Publish the draft only after all checks pass. 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.

.github/workflows/release-macos-arm64.yml

@@ -28,9 +28,15 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '24'
+          node-version: '24.18.1'
           cache: npm
 
+      - name: Pin npm
+        run: |
+          expected="$(node -p "require('./package.json').packageManager.split('@')[1]")"
+          npm install --global "npm@${expected}"
+          test "$(npm --version)" = "$expected"
+
       - name: Install dependencies
         run: npm ci
 
@@ -55,6 +61,7 @@ jobs:
           dmg="apps/desktop/release/Maka-${version}-mac-arm64.dmg"
           zip="apps/desktop/release/Maka-${version}-mac-arm64.zip"
           update_yml="apps/desktop/release/latest-mac.yml"
+          cli="apps/desktop/release/Maka-${version}-cli-mac-arm64.zip"
 
           if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
             echo "Tag ${tag} already exists." >&2
@@ -71,6 +78,7 @@ jobs:
             echo "dmg=${dmg}"
             echo "zip=${zip}"
             echo "update_yml=${update_yml}"
+            echo "cli=${cli}"
           } >> "$GITHUB_OUTPUT"
 
       - name: Package notarized app and signed DMG
@@ -104,10 +112,27 @@ jobs:
             --context context:primary-signature \
             --verbose=4 \
             "$DMG_PATH"
-
       - name: Verify the final DMG
         run: npm run verify:macos-arm64 -- "${{ steps.release.outputs.dmg }}"
 
+      - name: Package signed and notarized standalone CLI and TUI
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_API_KEY: ${{ runner.temp }}/AuthKey_Maka.p8
+          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          MAKA_CLI_RELEASE_SIGNING: '1'
+        run: npm run package:macos-arm64-cli
+
+      - name: Verify the standalone CLI and TUI
+        env:
+          MAKA_CLI_REQUIRE_RELEASE_SIGNING: '1'
+        run: npm run verify:macos-arm64-cli -- "${{ steps.release.outputs.cli }}"
+
+      - name: Remove the temporary notarization key
+        run: rm -f "${{ runner.temp }}/AuthKey_Maka.p8"
+
       - name: Create draft GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -126,6 +151,8 @@ jobs:
             "${DMG_PATH}.sha256" \
             "${{ steps.release.outputs.zip }}" \
             "${{ steps.release.outputs.update_yml }}" \
+            "${{ steps.release.outputs.cli }}" \
+            "${{ steps.release.outputs.cli }}.sha256" \
             --draft \
             --target "$GITHUB_SHA" \
             --title "Maka ${RELEASE_VERSION}" \

package.json

@@ -7,6 +7,9 @@
     "node": ">=22.19.0"
   },
   "packageManager": "npm@11.12.1",
+  "releaseToolchain": {
+    "node": "24.18.1"
+  },
   "type": "module",
   "workspaces": [
     "packages/core",
@@ -45,7 +48,9 @@
     "check:third-party-notices": "node scripts/generate-third-party-notices.mjs --check",
     "check:release": "npm run check:stale && npm run check:third-party-notices && node scripts/check-dead-css.mjs --check",
     "package:macos-arm64": "node scripts/package-macos-arm64.mjs",
+    "package:macos-arm64-cli": "node scripts/package-macos-arm64-cli.mjs",
     "verify:macos-arm64": "node scripts/verify-macos-arm64-dmg.mjs",
+    "verify:macos-arm64-cli": "node scripts/verify-macos-arm64-cli.mjs",
     "measure:session-bundle": "node scripts/measure-session-bundle.mjs",
     "astryx:theme": "node scripts/build-astryx-theme.mjs",
     "sync:model-metadata": "node scripts/sync-model-metadata.mjs",

scripts/macos-arm64-release.test.mjs

@@ -1,6 +1,9 @@
 import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
+import { access, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import test from 'node:test';
+import { parse as parseYaml } from 'yaml';
 
 const signingEnvironment = {
   CSC_LINK: 'base64-certificate',
@@ -49,6 +52,250 @@ test('release tooling fails closed on unsupported hosts, signing, and architectu
   );
 });
 
+test('standalone CLI derives its workspace and pinned toolchain invariants', async () => {
+  const {
+    assertMacosArm64CliHost,
+    assertOfficialNodeRuntime,
+    assertReleaseSigningEnvironment,
+    collectWorkspaceDependencyClosure,
+    macosArm64CliInstallArgs,
+    packageMacosArm64Cli,
+    releaseToolchainFromManifest,
+    resolveMacosArm64CliArtifactPaths,
+  } = await import(new URL('package-macos-arm64-cli.mjs', import.meta.url));
+  const { verifyMacosArm64Cli } = await import(
+    new URL('verify-macos-arm64-cli.mjs', import.meta.url)
+  );
+
+  assert.doesNotThrow(() => assertMacosArm64CliHost('darwin', 'arm64'));
+  assert.throws(() => assertMacosArm64CliHost('darwin', 'x64'), /Apple Silicon macOS host/);
+  await assert.rejects(
+    packageMacosArm64Cli({ platform: 'linux', arch: 'x64' }),
+    /Apple Silicon macOS host/,
+  );
+  await assert.rejects(
+    verifyMacosArm64Cli('/missing', { platform: 'linux', arch: 'x64' }),
+    /Apple Silicon macOS host/,
+  );
+
+  assert.deepEqual(
+    releaseToolchainFromManifest({
+      packageManager: 'npm@11.12.1',
+      releaseToolchain: { node: '24.18.1' },
+    }),
+    { nodeVersion: '24.18.1', npmVersion: '11.12.1' },
+  );
+  assert.throws(
+    () => releaseToolchainFromManifest({ packageManager: 'npm@latest' }),
+    /exact releaseToolchain\.node/,
+  );
+
+  const manifests = new Map([
+    ['maka-agent', { dependencies: { '@maka/core': '0.1.0', thirdParty: '1.0.0' } }],
+    ['@maka/core', { dependencies: { '@maka/storage': '0.1.0' } }],
+    ['@maka/storage', { dependencies: {} }],
+    ['@maka/unrelated', { dependencies: {} }],
+  ]);
+  assert.deepEqual(collectWorkspaceDependencyClosure('maka-agent', manifests), [
+    '@maka/core',
+    '@maka/storage',
+    'maka-agent',
+  ]);
+  manifests.get('@maka/core').dependencies['@maka/missing'] = '0.1.0';
+  assert.throws(
+    () => collectWorkspaceDependencyClosure('maka-agent', manifests),
+    /not in workspaces/,
+  );
+
+  const installArgs = macosArm64CliInstallArgs();
+  assert.equal(installArgs[0], 'ci');
+  assert.equal(installArgs.includes('--prefix'), false);
+  assert.ok(installArgs.includes('maka-agent'));
+  assert.ok(resolveMacosArm64CliArtifactPaths('1.2.3').archivePath.endsWith('.zip'));
+
+  assert.doesNotThrow(() =>
+    assertOfficialNodeRuntime({
+      actualVersion: '24.18.1',
+      expectedVersion: '24.18.1',
+      architectures: 'arm64\n',
+      signature:
+        'flags=0x10000(runtime)\nAuthority=Developer ID Application: Node.js Foundation (HX7739G8FX)',
+      linkedLibraries: [
+        '/System/Library/Frameworks/Security.framework/Versions/A/Security',
+        '/usr/lib/libSystem.B.dylib',
+      ],
+    }),
+  );
+  assert.throws(
+    () =>
+      assertOfficialNodeRuntime({
+        actualVersion: '24.18.1',
+        expectedVersion: '24.18.1',
+        architectures: 'arm64\n',
+        signature:
+          'flags=0x10000(runtime)\nAuthority=Developer ID Application: Node.js Foundation (HX7739G8FX)',
+        linkedLibraries: ['@rpath/libnode.147.dylib', '/opt/homebrew/opt/libuv/lib/libuv.1.dylib'],
+      }),
+    /not self-contained/,
+  );
+  assert.throws(() => assertReleaseSigningEnvironment({}), /CSC_LINK/);
+  assert.doesNotThrow(() => assertReleaseSigningEnvironment(signingEnvironment));
+});
+
+test('CLI release rejects unsafe archives, false TUI readiness, and crash exits', async () => {
+  const { assertAcceptedNotarization } = await import(
+    new URL('package-macos-arm64-cli.mjs', import.meta.url)
+  );
+  const { assertExpectedTuiExit, assertSafeCliArchiveEntries, isTuiReadyOutput } = await import(
+    new URL('verify-macos-arm64-cli.mjs', import.meta.url)
+  );
+
+  assert.doesNotThrow(() =>
+    assertSafeCliArchiveEntries(
+      ['Maka-1-cli-mac-arm64/', 'Maka-1-cli-mac-arm64/bin/maka'],
+      'Maka-1-cli-mac-arm64',
+    ),
+  );
+  assert.throws(
+    () => assertSafeCliArchiveEntries(['../escape'], 'Maka-1-cli-mac-arm64'),
+    /Unsafe CLI archive entry/,
+  );
+  assert.throws(
+    () =>
+      assertSafeCliArchiveEntries(['Maka-1-cli-mac-arm64/libexec/._node'], 'Maka-1-cli-mac-arm64'),
+    /Unsafe CLI archive entry/,
+  );
+
+  assert.equal(isTuiReadyOutput('Error loading /tmp/Maka-1-cli-mac-arm64/addon.node'), false);
+  assert.equal(isTuiReadyOutput('无法启动 Maka：还没有可用的模型连接。'), false);
+  assert.equal(isTuiReadyOutput('陪你把事做完'), true);
+  assert.throws(
+    () =>
+      assertExpectedTuiExit({
+        ready: true,
+        stopRequested: true,
+        exitCode: 1,
+        signal: 0,
+        output: '陪你把事做完\ncrash',
+      }),
+    /crashed after startup/,
+  );
+  assert.doesNotThrow(() =>
+    assertExpectedTuiExit({
+      ready: true,
+      stopRequested: true,
+      exitCode: 0,
+      signal: 0,
+      output: '陪你把事做完',
+    }),
+  );
+  assert.doesNotThrow(() => assertAcceptedNotarization('{"status":"Accepted"}'));
+  assert.throws(() => assertAcceptedNotarization('{"status":"Invalid"}'), /status Invalid/);
+});
+
+test('CLI staging removes test output and rejects dangling symlinks', async () => {
+  const { assertNoDanglingSymlinks, pruneTestArtifacts } = await import(
+    new URL('package-macos-arm64-cli.mjs', import.meta.url)
+  );
+  const root = await mkdtemp(join(tmpdir(), 'maka-cli-unit-'));
+  try {
+    const dist = join(root, 'dist');
+    await mkdir(join(dist, '__tests__'), { recursive: true });
+    await Promise.all([
+      writeFile(join(dist, 'index.js'), 'export {};\n'),
+      writeFile(join(dist, 'feature.test.js'), 'throw new Error();\n'),
+      writeFile(join(dist, '__tests__', 'fixture.js'), 'throw new Error();\n'),
+    ]);
+    await pruneTestArtifacts(dist);
+    await access(join(dist, 'index.js'));
+    await assert.rejects(access(join(dist, 'feature.test.js')), { code: 'ENOENT' });
+    await assert.rejects(access(join(dist, '__tests__')), { code: 'ENOENT' });
+
+    await mkdir(join(root, 'target'));
+    await symlink('target', join(root, 'valid-link'));
+    await assertNoDanglingSymlinks(root);
+    await symlink('missing', join(root, 'dangling-link'));
+    await assert.rejects(assertNoDanglingSymlinks(root), /Dangling symlink/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('CLI staging applies repository dependency patches before relocation', async () => {
+  const { applyDependencyPatches, listDependencyPatchNames } = await import(
+    new URL('package-macos-arm64-cli.mjs', import.meta.url)
+  );
+  const root = await mkdtemp(join(tmpdir(), 'maka-cli-patches-'));
+  try {
+    const calls = [];
+    const expectedPatchNames = await listDependencyPatchNames();
+    assert.ok(expectedPatchNames.includes('@ai-sdk+provider-utils+5.0.11.patch'));
+    const appliedPatchNames = await applyDependencyPatches(root, {
+      patchPackageEntry: '/tools/patch-package/index.js',
+      run: async (command, args, options) => {
+        calls.push({ command, args, options });
+      },
+    });
+    assert.deepEqual(appliedPatchNames, expectedPatchNames);
+    await Promise.all(expectedPatchNames.map((name) => access(join(root, 'patches', name))));
+    assert.deepEqual(calls, [
+      {
+        command: process.execPath,
+        args: ['/tools/patch-package/index.js', '--error-on-fail'],
+        options: { cwd: root, env: process.env },
+      },
+    ]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('packaged streaming smoke rejects provider-utils index-hole regressions', async () => {
+  const { assertPatchedStreamingToolCalls } = await import(
+    new URL('verify-macos-arm64-cli.mjs', import.meta.url)
+  );
+  const expectedCalls = [
+    { type: 'tool-call', toolCallId: 'call_1', toolName: 'read_file', input: '{"path":"a.txt"}' },
+    { type: 'tool-call', toolCallId: 'call_2', toolName: 'read_file', input: '{"path":"b.txt"}' },
+    { type: 'finish' },
+  ];
+  assert.doesNotThrow(() => assertPatchedStreamingToolCalls(expectedCalls));
+  assert.throws(
+    () => assertPatchedStreamingToolCalls([{ type: 'error', error: new Error('index hole') }]),
+    /failed to finish/,
+  );
+  assert.throws(
+    () => assertPatchedStreamingToolCalls([expectedCalls[1], expectedCalls[0], { type: 'finish' }]),
+    /reordered or dropped/,
+  );
+});
+
+test('release workflow pins the toolchain and gates CLI publication on signing', async () => {
+  const workflow = parseYaml(
+    await readFile(
+      new URL('../.github/workflows/release-macos-arm64.yml', import.meta.url),
+      'utf8',
+    ),
+  );
+  const steps = workflow.jobs.release.steps;
+  const setupNode = steps.find((step) => step.name === 'Set up Node.js');
+  const packageCli = steps.find(
+    (step) => step.name === 'Package signed and notarized standalone CLI and TUI',
+  );
+  const verifyCli = steps.find((step) => step.name === 'Verify the standalone CLI and TUI');
+  const release = steps.find((step) => step.name === 'Create draft GitHub Release');
+  const cleanupIndex = steps.findIndex(
+    (step) => step.name === 'Remove the temporary notarization key',
+  );
+
+  assert.equal(setupNode.with['node-version'], '24.18.1');
+  assert.equal(packageCli.env.MAKA_CLI_RELEASE_SIGNING, '1');
+  assert.equal(verifyCli.env.MAKA_CLI_REQUIRE_RELEASE_SIGNING, '1');
+  assert.match(release.run, /steps\.release\.outputs\.cli/);
+  assert.match(release.run, /steps\.release\.outputs\.cli \}\}\.sha256/);
+  assert.ok(cleanupIndex > steps.indexOf(verifyCli));
+});
+
 test('the packaged app is checked for every unsigned helper that could still be in a tree', async () => {
   // `apps/desktop/resources/bin` is gitignored, so removing a helper from the
   // repository does not remove it from the machine of anyone who prepared it