magus-cli 0.0.0-placeholder → 7.0.0

package/README.md

@@ -0,0 +1,309 @@
+# magus
+
+Manage a Claude Code setup — plugins, MCP servers, skills, CLI tools and the
+binaries plugins depend on — from a TUI, a CLI, or a committed team manifest.
+
+## Install
+
+```bash
+bun add -g magus-cli      # recommended
+npm install -g magus-cli  # also works
+```
+
+Updates go through magus itself, not the package manager:
+
+```bash
+magus upgrade
+```
+
+`upgrade` advances **magus**. `update` advances **your dependencies** — the
+plugins, CLI tools and skills your profile declares. Same split as every package
+manager, so the two are never confused.
+
+You get a self-contained binary for your platform (an `optionalDependencies`
+package gated on `os`/`cpu`). On a platform without a prebuilt binary the
+launcher falls back to running from source under Bun, so the install still works.
+
+## Two ways to use it
+
+**Interactive** — run `magus` with no arguments for the TUI. Good for
+exploring what is available and toggling things on one machine.
+
+**Declarative** — commit a `.claude/profiles.json` and run `magus install`.
+Good for making a teammate's machine match yours. This is the
+[team configuration guide](docs/team-configuration.md).
+
+## Commands
+
+```
+magus                    Open the interactive TUI
+
+install [profile]           Install a profile's plugins, binaries, skills and
+                            env at the manifest's PINNED versions, then activate
+                            it. No argument = every profile.
+  --check                   Report drift only, write nothing (CI gate)
+  --yes, -y                 Skip the confirmation prompt
+  --force                   Discard unsynced local edits instead of refusing
+update [profile]            Bring the ACTIVE profile up to date: install what it
+                            declares but this machine lacks, and advance every
+                            "latest" pin to the newest published version.
+  --check                   Report only, write nothing (exits 1 if anything is
+                            missing or known to be behind)
+  --yes, -y                 Skip the confirmation prompt
+profile list                Show every profile; ● marks the active one
+profile show <name>         Print a profile's fully resolved closure
+profile switch <name>       Repoint the active profile — offline, no reinstall
+profile init                Write .claude/profiles.json from this project's setup
+profile sync                Promote local edits back into .claude/profiles.json
+doctor [--fix]              Check binary deps, profile symlinks, conventions
+
+claude [args...]            Check for plugin updates (1h cache), then run claude
+  --force, -f               Force the update check
+upgrade                     Update magus itself
+--version, -v               Version + update check
+--help, -h                  This list
+--theme light|dark          Force the palette. Otherwise: MAGUS_THEME, then
+                            TERM_THEME, then a 250 ms terminal query, then
+                            COLORFGBG, then dark. Only the exact words
+                            "light"/"dark" count.
+```
+
+### Light or dark
+
+magus decides once at startup, first answer wins: `--theme`, then the
+`MAGUS_THEME` variable, then `TERM_THEME`, then a bounded (250 ms) wait for
+the terminal's OSC 10/11 reply — only when stdin and stdout are both TTYs — then
+`COLORFGBG`, then dark. A word that is not exactly `light` or `dark` (so `auto`,
+`Light`, an empty value) is no opinion and the next step runs; when the flag is
+given a bad word, that is an error naming both accepted values.
+
+`TERM_THEME` and `MAGUS_THEME` are read from the process environment, never
+from a project's `.env`. Running from source needs `--no-env-file`, because Bun
+otherwise autoloads the cwd's `.env` before any code runs; the package scripts
+and the `bin/magus.js` source fallback already pass it, and the compiled
+binary never autoloads. The OSC 10/11 query itself is emitted by OpenTUI
+(0.1.107) when the renderer is created, regardless of the outcome; when an
+earlier step answered, magus never awaits or uses the reply, so first paint
+is not delayed and the terminal's answer has no influence.
+
+### install vs update
+
+They differ in one thing: whether the pins are allowed to move.
+
+| | `install` | `update` |
+|---|---|---|
+| Versions | exactly what the manifest pins | advances every `"latest"` pin |
+| Scope | every profile (or the one named) | the **active** profile |
+| Also does | materializes + activates the profile | nothing to the manifest |
+
+Both install whatever the profile declares and this machine lacks, so `update`
+covers the "I ticked it but never installed it" case on its own.
+
+**This is dependency management, not a package manager.** There is no resolver,
+no lockfile and no version negotiation. The job is: everything the profile
+declares is installed, and current.
+
+That matters for exact pins. `claude plugin install` takes no version argument —
+it installs whatever the marketplace publishes now — so a pin naming anything
+else cannot be satisfied. `update` plans against the version it can actually
+get, notes the shortfall, and moves on:
+
+```
+  dev@magus   = 9.9.9  (manifest pins 4.6.1; the marketplace offers only 9.9.9)
+```
+
+It records what actually landed, never the pin, and it does **not** fail over
+the difference — an unsatisfiable pin is a standing property of the manifest,
+not something a given run did wrong. Pin drift is gated where it always was:
+`magus install --check` with `strictVersions` in the manifest.
+
+**`update` only ever moves forward.** Nothing here can downgrade — the installer
+takes no version — so an install that is already ahead of what the marketplace
+publishes is left alone rather than dragged back. A plan that tried would emit a
+step that runs, reports success, changes nothing, and reappears on every
+subsequent run.
+
+`--check` fails on things that are **missing or known to be behind**. It
+deliberately does not fail on the two items that get re-fetched every run
+regardless: an already-installed skill (a manifest skill ref carries no content
+hash, so there is nothing to compare) and a present unpinned binary (no version
+probe exists, only present/absent). A gate that can never pass gets switched
+off, so it only fires on real drift.
+
+Neither command needs a manifest to exist first. In a repo without
+`.claude/profiles.json`, both offer to write one describing the project as it
+stands — that is `magus profile init`, which you can also run on its own.
+Adoption reads the project's own `.claude/settings.json`; if that enables
+nothing it falls back to your user-scope settings and says so, because the file
+is meant to be committed and one machine's global set is not a team contract.
+Machine-only keys are stripped, and any settings value naming a path under your
+home directory is flagged for review.
+
+`--yes` alone will **not** create a manifest. It means "don't ask me about the
+command I ran", and someone running `magus update --yes` in CI did not ask to
+author their team's committed contract. Creating it needs a human at the prompt,
+or `magus profile init`.
+
+`magus doctor` exits non-zero when it finds a problem, so it works as a CI
+check. So does `magus install --check`.
+
+## What the TUI covers
+
+| Screen | What it manages |
+|---|---|
+| Plugins | Install, enable, disable; shows version changes and newly installed plugins |
+| Skills | Browse and install skills from configured skill repos |
+| MCP | Add MCP servers from a curated catalog |
+| Settings | Claude Code settings, from a catalog of known keys |
+| Profiles | Saved plugin sets (the TUI's own, older profile concept) |
+| CLI Tools | Install claudish, mnemex and friends via the right package manager |
+| Git State | Gitignore conventions and repo hygiene |
+| Alias | Shell alias + flag management for launching `claude` |
+| Styles | Communication style presets, composed into one native output style |
+
+Navigate with `↑/↓` or `j/k`, `Enter` to select, `r` to refresh, `?` for help,
+`q`/`Escape` to go back. Number keys `1`–`9` jump straight to a screen.
+
+## Styles
+
+Claude Code activates exactly one output style at a time. The Styles screen (`9`)
+composes several rule blocks into that one style, so choices that would otherwise
+compete for the single slot end up in one file.
+
+One **verbosity axis** — pick exactly one of `direct`, `explanatory`, or `terse` —
+plus any number of free modifiers:
+
+| Preset | Effect |
+|---|---|
+| `direct` | Lead with the answer, minimal preamble |
+| `explanatory` | Teach as you go, more context per step |
+| `terse` | Shortest useful output |
+| `no-slop` | Bans filler, hype, and AI vocabulary |
+| `asd-ste100` | ASD-STE100 Simplified Technical English: sentences that survive one read |
+| `evidence-first` | Claims must carry a citation, command output, or file reference |
+| `calibrated` | State confidence honestly; no false certainty |
+| `plain-language` | Prefer plain words over jargon |
+| `structured` | Headings, tables, and lists over long paragraphs |
+| `terminology` | Enforce project-specific vocabulary, filled in from your codebase |
+
+Two verbosity presets is the one combination that does not work: `terse` says "do
+not explain unless asked" and `explanatory` says "explain the specific choice", so
+together they cancel and the model resolves the contradiction differently every
+turn. Everything else stacks.
+
+The presets live in `src/data/styles/*.md` and are compiled into the binary, so
+they are always the version this magus was built from.
+
+### What gets written
+
+```
+.claude/output-styles/composed.md    the composed rules (generated — do not hand-edit)
+.claude/settings.json                "outputStyle": "composed"
+.claude/style.json                   the declaration — commit this to share it
+```
+
+With a profile active the file is named `composed-<profile>` and the choice is
+also recorded in `.claude/profiles.json`, because `magus install` rebuilds
+`settings.json` from the manifest and would otherwise drop it.
+
+`style.json` is the reviewable statement of what the project wants; `composed.md`
+is the artifact Claude Code reads. A teammate who clones the repo gets the
+declaration, and magus tells them when their local artifact does not match it.
+
+### Styles you already have
+
+Output styles you wrote yourself compose too — magus finds them in
+`~/.claude/output-styles/` and `.claude/output-styles/` and lists them alongside
+the presets. Community styles can be fetched from their source repository on an
+explicit action, and are cached outside `~/.claude/output-styles/` so a re-fetch
+never overwrites something you wrote.
+
+Built-in styles ship inside the Claude Code binary rather than on disk, so there
+is no file to import until you capture one. `--discover` names the set the
+installed version actually has — it was `Concise`, `Explanatory`, `Learning` and
+`Proactive` on Claude Code 2.1.239, and Anthropic adds to it:
+
+```bash
+bun scripts/capture-builtin.ts --discover   # what Anthropic ships today
+bun scripts/capture-builtin.ts --all        # capture every built-in
+bun scripts/capture-builtin.ts --check      # what fell behind after an upgrade
+```
+
+Each capture runs one real `claude -p` round trip behind a transparent proxy and
+records the system prompt Claude Code actually sent, writing
+`~/.claude/output-styles/builtin-<name>.md`. Captures are per machine and stamped
+with the Claude Code version they came from — **re-run `--check` after every
+upgrade**. Nothing is committed to this repo: the text is Anthropic's, and it
+changes on their release schedule, not ours.
+
+### Coding rules stay on
+
+Every generated style sets `keep-coding-instructions: true`. Without that flag
+Claude Code drops its own coding-discipline rules from the system prompt, and a
+setting about how to *communicate* has no business switching off how code gets
+written. `force-for-plugin` is never set either — that would override your own
+`/output-style` choice.
+
+## Files magus touches
+
+| Path | Owner | What magus does |
+|---|---|---|
+| `.claude/profiles.json` | you, committed | reads it; `profile sync` writes to it |
+| `.claude/_profiles/<name>/` | magus, gitignored | generated build output |
+| `.claude/settings.json` | Claude Code | in profile mode, a symlink into `_profiles/` |
+| `.claude/settings.local.json` | you, gitignored | env values collected during install |
+| `.claude/style.json` | you, committed | the project's declared style — written on apply |
+| `.claude/output-styles/composed*.md` | magus, committed | the generated style Claude Code reads |
+| `.mcp.json` | Claude Code | in profile mode, a symlink into `_profiles/` |
+| `~/.claude/plugins/*` | Claude Code | never written directly — always via the `claude` CLI |
+
+magus never hand-edits Claude Code's own registries
+(`installed_plugins.json`, `known_marketplaces.json`, the plugin cache). Those go
+through `claude plugin ...` so Claude Code stays the single writer.
+
+## Development
+
+```bash
+bun install
+bun test                # full suite
+bun run typecheck
+bun run lint
+bun run src/main.tsx    # run from source
+bun run build:binaries  # cross-compile all platform binaries + their packages
+```
+
+Tests run per-file isolated in CI (`bun run test:ci`) because `mock.module`
+leaks across files in a shared process.
+
+**Do not bump `@opentui` past 0.1.x.** 0.4.x breaks `bun build --compile`: it
+resolves tree-sitter workers eagerly, bypassing the `OTUI_ASSET_ROOT` override,
+so a bare `import "@opentui/core"` crashes at import time in the compiled
+binary. Re-run the compile spike before changing that pin.
+
+## Releasing
+
+Tag-driven. `.github/workflows/magus-release.yml` fires on `tools/magus/v*`:
+
+1. **verify** — install, typecheck, `test:ci`, version and optional-deps gates
+2. **binaries** — a matrix building each target on its **native** runner
+   (`bun --compile` cannot cross-compile in CI because opentui ships a
+   per-platform native library)
+3. **publish** — platform packages first, main package last, so its
+   `optionalDependencies` already resolve
+
+```bash
+# bump "version" AND the three optionalDependencies to match
+bun run check:optional-deps
+git commit -am "feat(magus): vX.Y.Z - description"
+git tag -a tools/magus/vX.Y.Z -m "Release message"
+git push origin main --tags
+```
+
+Auth is npm OIDC trusted publishing — the workflow references no secrets. Adding
+a **new** platform target needs a one-time manual publish to create the package
+name (OIDC can only authenticate against a package that already exists); see
+[`docs/npm-trusted-publishing-setup.md`](../../docs/npm-trusted-publishing-setup.md).
+
+## License
+
+MIT

package/bin/magus.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * magus launcher.
+ *
+ * Prefers a prebuilt, self-contained binary shipped as a per-platform
+ * optionalDependency (magus-cli-<platform>-<arch>) — that binary embeds the Bun
+ * runtime, so it runs without Bun installed. Falls back to running from source
+ * via Bun for dev checkouts and unsupported platforms.
+ *
+ * Set MAGUS_NO_BINARY=1 to skip the prebuilt binary and force the source
+ * path. That escape hatch exists because the launcher PREFERS the binary: when
+ * a shipped binary cannot start on a given machine, without it magus is a
+ * hard block rather than a slow start.
+ *
+ * This file must stay self-contained and import only node: builtins. Its tests
+ * copy it into a throwaway tree, where any relative import would not resolve.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { constants } from "node:os";
+
+const require = createRequire(import.meta.url);
+const args = process.argv.slice(2);
+const { platform, arch } = process;
+
+const ISSUES_URL = "https://github.com/MadAppGang/magus/issues";
+
+/**
+ * The four signals a person sends on purpose. Everything else is a crash.
+ *
+ * The rule is deliberately inverted from the obvious one. An allowlist of
+ * crash signals leaves holes: SIGABRT is what a Bun/JSC panic raises, which is
+ * exactly the "this binary is broken, use source" case, and it would fall
+ * through the allowlist into the old masked path.
+ */
+const USER_SIGNALS = new Set(["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"]);
+
+/**
+ * How long after exec a crash still counts as "it never started".
+ *
+ * An invalid code signature kills the binary in single-digit milliseconds, at
+ * exec, before any output. A `kill -9` against a running TUI, or an OOM kill,
+ * lands seconds later. Without this gate the fix would trade a silent exit 0
+ * for a surprise relaunch of an app the user deliberately killed.
+ */
+const CRASH_FALLBACK_WINDOW_MS = 2000;
+
+/** Shell convention: a signal death is 128 + the signal number. */
+function exitCodeForSignal(signal) {
+	const number = constants.signals[signal];
+	return typeof number === "number" ? 128 + number : 1;
+}
+
+// Set when a binary was found and tried but could not deliver a result. It
+// changes what the source path says if IT then fails: "no prebuilt binary for
+// this platform" is true when none was installed and a flat contradiction when
+// one was just reported as killed.
+let binaryFailed = false;
+
+// 1. Prefer the prebuilt platform binary, unless the source path is forced.
+const forceSource = process.env.MAGUS_NO_BINARY === "1";
+const pkgName = `magus-cli-${platform}-${arch}`;
+let binaryPath = null;
+try {
+	const pkgJson = require.resolve(`${pkgName}/package.json`);
+	const candidate = join(dirname(pkgJson), "bin", "magus");
+	if (existsSync(candidate)) binaryPath = candidate;
+} catch {
+	// optional dep not installed for this platform — fall through
+}
+
+if (binaryPath && !forceSource) {
+	const startedAt = Date.now();
+	const result = spawnSync(binaryPath, args, { stdio: "inherit" });
+	const elapsedMs = Date.now() - startedAt;
+
+	if (!result.error) {
+		// `status === null` is the authoritative "did not exit normally" marker,
+		// NOT the truthiness of `signal`. Node writes an empty string into
+		// `signal` for a signal it has no name for (Linux real-time signals,
+		// SIGRTMIN+n), and "" is falsy — so branching on the signal would fall
+		// straight back into the `status ?? 0` this release exists to remove.
+		if (result.status !== null) process.exit(result.status);
+
+		const signalName = result.signal || "an unnamed signal";
+		const deliberate =
+			USER_SIGNALS.has(result.signal) ||
+			elapsedMs >= CRASH_FALLBACK_WINDOW_MS;
+		if (deliberate) process.exit(exitCodeForSignal(result.signal));
+
+		binaryFailed = true;
+		// The elapsed time is measured; "before producing any output" is not —
+		// the child ran under stdio: "inherit", so this process never saw its
+		// output and must not claim there was none.
+		console.error(
+			`magus: the prebuilt binary was killed by ${signalName} ${elapsedMs}ms after it started.\n` +
+				"\n" +
+				`  binary:   ${binaryPath}\n` +
+				`  platform: ${platform}-${arch}\n` +
+				"\n" +
+				"On macOS this almost always means the binary's code signature is invalid and the\n" +
+				"kernel refused to run it. Confirm with:\n" +
+				"\n" +
+				`  codesign --verify --strict "${binaryPath}"\n` +
+				"\n" +
+				"Falling back to running from source via Bun. To skip the binary permanently:\n" +
+				"  export MAGUS_NO_BINARY=1\n" +
+				"\n" +
+				`Please report this: ${ISSUES_URL}`,
+		);
+		// fall through to the source path
+	} else {
+		// A binary that could not be executed AT ALL (ENOENT, EACCES, bad arch)
+		// also leaves status null. Say so and fall through.
+		binaryFailed = true;
+		console.error(
+			`magus: prebuilt binary could not start (${result.error.message}); falling back to source.`,
+		);
+	}
+}
+
+// 2. Fallback: run from source via Bun.
+const here = dirname(fileURLToPath(import.meta.url));
+const mainSrc = join(here, "..", "src", "main.tsx");
+// --no-env-file: Bun autoloads the cwd's .env into process.env before any user
+// code runs, and the theme snapshot in main.tsx must precede any .env merge
+// (loadProjectDotenv is the only merger). The compiled binary never autoloads.
+const bunRun = spawnSync("bun", ["--no-env-file", mainSrc, ...args], {
+	stdio: "inherit",
+});
+if (bunRun.error) {
+	// Two different states reach here, and one message for both is a lie in one
+	// of them. A user who installed magus from npm on macOS 27 and has no
+	// Bun hits the FIRST branch — telling them no binary exists for their
+	// platform contradicts the diagnostic printed seconds earlier, and
+	// "use a supported platform" is advice for a problem they do not have.
+	if (binaryFailed) {
+		console.error(
+			`magus: the prebuilt binary for ${platform}-${arch} is unusable on this machine, and Bun is not installed to fall back to.\n` +
+				"\n" +
+				"Reinstall to pick up a working binary:\n" +
+				"  npm install -g magus-cli@latest\n" +
+				"\n" +
+				"Or install Bun (https://bun.sh) so the source path can run.\n" +
+				`Please report this: ${ISSUES_URL}`,
+		);
+	} else {
+		console.error(
+			`magus: no prebuilt binary for ${platform}-${arch}, and Bun is not installed.`,
+		);
+		console.error("Install Bun (https://bun.sh) or use a supported platform.");
+	}
+	process.exit(1);
+}
+// Same masking bug, second site, keyed the same way: `status === null` decides,
+// not the signal. There is no binary here and nowhere left to fall back to, so
+// this reports and exits — no codesign hint, which would be nonsense for a Bun
+// crash.
+if (bunRun.status !== null) process.exit(bunRun.status);
+if (!USER_SIGNALS.has(bunRun.signal)) {
+	console.error(
+		`magus: running from source was killed by ${bunRun.signal || "an unnamed signal"}.\n` +
+			`Please report this: ${ISSUES_URL}`,
+	);
+}
+process.exit(exitCodeForSignal(bunRun.signal));

package/package.json

@@ -1,7 +1,71 @@
 {
   "name": "magus-cli",
-  "version": "0.0.0-placeholder",
-  "description": "Placeholder — real package is published by CI.",
+  "version": "7.0.0",
+  "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
+  "type": "module",
+  "main": "src/main.tsx",
+  "bin": {
+    "magus": "bin/magus.js"
+  },
+  "scripts": {
+    "start": "bun --no-env-file src/main.tsx",
+    "dev": "bun --watch --no-env-file src/main.tsx",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "format": "biome format --write src/",
+    "test": "bun test",
+    "test:ci": "bun scripts/test-isolated.ts",
+    "test:update": "bun test --update-snapshots",
+    "build:binaries": "bun scripts/build-binaries.ts",
+    "check:optional-deps": "bun scripts/check-optional-deps.ts"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "plugins",
+    "tui",
+    "cli",
+    "opentui",
+    "react"
+  ],
+  "author": "Jack Rudenko <i@madappgang.com>",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/MadAppGang/magus-src.git" }
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MadAppGang/magus"
+  },
+  "bugs": {
+    "url": "https://github.com/MadAppGang/magus/issues"
+  },
+  "homepage": "https://github.com/MadAppGang/magus/tree/main/tools/magus#readme",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/"
+  ],
+  "dependencies": {
+    "@opentui/core": "^0.1.75",
+    "@opentui/react": "^0.1.75",
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "react": "^19.0.0",
+    "semver": "^7.6.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.0.0",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.6.3"
+  },
+  "optionalDependencies": {
+    "magus-cli-darwin-arm64": "7.0.0",
+    "magus-cli-darwin-x64": "7.0.0",
+    "magus-cli-linux-x64": "7.0.0"
+  }
 }

package/scripts/build-binaries.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+/**
+ * Build per-platform, self-contained magus binaries and their npm packages.
+ *
+ * Each target is compiled with `bun build --compile --target=bun-<os>-<arch>`,
+ * producing a binary that embeds the Bun runtime (runs without Bun installed).
+ * The output is a publishable package per platform under dist-binaries/:
+ *
+ *   dist-binaries/magus-cli-darwin-arm64/
+ *     package.json   (os/cpu restricted, no `bin` — the launcher execs it)
+ *     bin/magus   (the compiled binary)
+ *
+ * The main `magus` package lists these as optionalDependencies; npm installs
+ * only the one matching the host os/cpu, and bin/magus.js execs it.
+ *
+ * Hard constraint: magus pins @opentui 0.1.x — 0.4.x breaks --compile.
+ *
+ * Hard constraint: every darwin binary is re-signed and verified here. The
+ * signature --compile leaves behind does not cover the appended bundle, and
+ * macOS 27 kills such a binary at exec. See src/services/binary-signing.ts.
+ *
+ * Hard constraint: the two --no-compile-autoload flags below must stay. A Bun
+ * standalone executable autoloads .env and bunfig.toml from its CURRENT
+ * DIRECTORY by default, and magus reads neither on purpose. Bun 1.4.0 dies
+ * in the .env path when that file is a symlink pointing at a FIFO — exactly how
+ * 1Password serves secrets into a git worktree — exiting 1 with nothing on
+ * stdout or stderr, because the crash lands before any JS runs and therefore
+ * before any error handler exists. A FIFO also hands its bytes to whoever opens
+ * it first, so an autoloading magus can swallow the secrets a dev server was
+ * waiting for. Dropping the flags re-arms both failures.
+ */
+
+import { $ } from "bun";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import path from "node:path";
+import pkg from "../package.json";
+import { signAndVerify } from "../src/services/binary-signing.js";
+
+interface Target {
+	os: "darwin" | "linux";
+	cpu: "arm64" | "x64";
+	bunTarget: string;
+}
+
+const TARGETS: Target[] = [
+	{ os: "darwin", cpu: "arm64", bunTarget: "bun-darwin-arm64" },
+	{ os: "darwin", cpu: "x64", bunTarget: "bun-darwin-x64" },
+	{ os: "linux", cpu: "x64", bunTarget: "bun-linux-x64" },
+];
+
+const version = (pkg as { version: string }).version;
+const root = path.join(import.meta.dir, "..");
+const distRoot = path.join(root, "dist-binaries");
+const entry = path.join(root, "src", "main.tsx");
+
+// Optional filter: `bun scripts/build-binaries.ts darwin-arm64`
+const only = process.argv[2];
+
+// Only a full build purges the whole tree. Scoping a filtered build to its own
+// target means `build:binaries linux-x64` on a Linux host does not first wipe
+// dist-binaries/ and then throw on the darwin guard below, leaving the user
+// with neither the old output nor the one target they could actually build.
+if (!only) await rm(distRoot, { recursive: true, force: true });
+
+for (const t of TARGETS) {
+	const id = `${t.os}-${t.cpu}`;
+	if (only && only !== id) continue;
+
+	const pkgName = `magus-cli-${id}`;
+	const outDir = path.join(distRoot, pkgName);
+	const binPath = path.join(outDir, "bin", "magus");
+
+	// `codesign` is macOS-only, and an unsigned darwin binary is killed at exec
+	// by macOS 27. Building one anywhere else produces an artifact that cannot
+	// be gated, which is precisely how the broken binaries shipped.
+	if (t.os === "darwin" && process.platform !== "darwin") {
+		throw new Error(
+			`Cannot build ${pkgName} on ${process.platform}: darwin binaries must be signed, and codesign exists only on macOS. Build this target on a macOS runner, or name a buildable one: bun run build:binaries linux-x64`,
+		);
+	}
+
+	await rm(outDir, { recursive: true, force: true });
+	await mkdir(path.join(outDir, "bin"), { recursive: true });
+
+	console.log(`Building ${pkgName} (${t.bunTarget})…`);
+	// The --no-compile-autoload flags are load-bearing; see the header.
+	await $`bun build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig --target=${t.bunTarget} ${entry} --outfile ${binPath}`;
+
+	// --compile signs the Mach-O, then appends the bundle after it, leaving a
+	// signature that does not cover the file. Re-sign and refuse to continue if
+	// the result does not verify.
+	signAndVerify(t, binPath);
+
+	// Platform package: os/cpu-restricted, ships only the binary, declares NO
+	// `bin` (the main package's launcher resolves and execs bin/magus).
+	const platformPkg = {
+		name: pkgName,
+		version,
+		description: `Prebuilt magus binary for ${id}`,
+		os: [t.os],
+		cpu: [t.cpu],
+		files: ["bin/"],
+		license: (pkg as { license: string }).license,
+		repository: (pkg as { repository: unknown }).repository,
+	};
+	await writeFile(
+		path.join(outDir, "package.json"),
+		`${JSON.stringify(platformPkg, null, 2)}\n`,
+	);
+}
+
+console.log(`\nDone. Packages in ${path.relative(process.cwd(), distRoot)}/`);
+console.log("Publish each with `npm publish` (then the main package).");