From fcd31b4c83c2fad51f81c63a5016f9f724fb7751 Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Mon, 9 Nov 2026 12:49:17 -0600 Subject: [PATCH 1/4] Install complete Atomic runtime through Homebrew --- .github/workflows/test.yml | 36 ++++++++++++++++ Formula/atomic.rb | 77 +++++++++++++++++++++++++++++++-- README.md | 70 ++++++++++++++++++++++++++---- scripts/update_formula.rb | 5 +++ scripts/update_formula_test.rb | 79 ++++++++++++++++++++++++++++++++++ 5 files changed, 254 insertions(+), 13 deletions(-) create mode 100644 .github/workflows/test.yml create mode 100644 scripts/update_formula_test.rb diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..ee417f4 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,36 @@ +name: Test tap + +on: + push: + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + updater: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.3" + - run: gem install minitest --no-document + - run: ruby scripts/update_formula_test.rb + + formula: + strategy: + fail-fast: false + matrix: + os: [macos-latest, ubuntu-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: Homebrew/actions/setup-homebrew@master + - name: Tap checked-out formula + run: brew tap --custom-remote atomicdotdev/tap "$GITHUB_WORKSPACE" + - name: Install complete release runtime + run: brew install --build-from-source --include-test atomicdotdev/tap/atomic + - name: Load installed runtime through Node-API + run: brew test atomicdotdev/tap/atomic diff --git a/Formula/atomic.rb b/Formula/atomic.rb index 01ad32e..775b4f3 100644 --- a/Formula/atomic.rb +++ b/Formula/atomic.rb @@ -1,6 +1,9 @@ # typed: false # frozen_string_literal: true +require "digest" +require "json" + # Homebrew formula for the Atomic CLI. # # Binary-based: downloads the prebuilt release archive for the user's @@ -17,12 +20,15 @@ class Atomic < Formula desc "Mathematically sound distributed version control system for the age of AI" homepage "https://github.com/atomicdotdev/atomic" license any_of: ["MIT", "Apache-2.0"] + revision 1 livecheck do url :stable strategy :github_latest end + depends_on "node" => :test + on_macos do if Hardware::CPU.arm? url "https://github.com/atomicdotdev/atomic/releases/download/v0.21.0/atomic-aarch64-apple-darwin.tar.gz" @@ -43,15 +49,78 @@ class Atomic < Formula end end + def native_library + return "libatomic.dylib" if OS.mac? && Hardware::CPU.arm? + + "libatomic.so" if OS.linux? && Hardware::CPU.intel? + end + def install - bin.install "atomic" + if (library = native_library) + manifest = JSON.parse(File.read("libatomic-runtime.json")) + if manifest.fetch("librarySha256") != Digest::SHA256.file(library).hexdigest + odie "Atomic runtime library checksum mismatch" + end + + libexec.install "atomic", library, "libatomic-runtime.json" + bin.install_symlink libexec/"atomic" + else + bin.install "atomic" + end end + # Homebrew can rewrite native linkage and re-sign the library. Hash the + # installed bytes; never change the producer's protobuf fingerprint. + post_install_steps( + type: "run", + command: RbConfig.ruby, + guards: [{ condition: "if_exists", path: "libatomic-runtime.json", base: "libexec" }], + writable_paths: [ + { path: "libatomic-runtime.json", base: "libexec" }, + { path: "libatomic-runtime.json.tmp", base: "libexec" }, + ], + args: ["-rjson", "-rdigest", "-e", <<~'RUBY', "{{libexec}}/libatomic-runtime.json"], + path = ARGV.fetch(0) + manifest = JSON.parse(File.read(path)) + library = File.join(File.dirname(path), manifest.fetch("library")) + manifest["librarySha256"] = Digest::SHA256.file(library).hexdigest + temporary = "#{path}.tmp" + File.write(temporary, "#{JSON.pretty_generate(manifest)}\n") + File.rename(temporary, path) + RUBY + ) + test do - # The binary should be installed and report a version matching this formula. assert_match version.to_s, shell_output("#{bin}/atomic --version") - - # `atomic --help` should list a core subcommand. assert_match "init", shell_output("#{bin}/atomic --help") + return unless (library = native_library) + + manifest = JSON.parse((libexec/"libatomic-runtime.json").read) + assert_equal 1, manifest.fetch("schemaVersion") + assert_equal version.to_s, manifest.fetch("version") + assert_equal library, manifest.fetch("library") + assert_equal Digest::SHA256.file(libexec/library).hexdigest, manifest.fetch("librarySha256") + + (testpath/"runtime.cjs").write <<~JS + const assert = require('node:assert/strict'); + const { createHash } = require('node:crypto'); + const { readFileSync, realpathSync } = require('node:fs'); + const { dirname, join } = require('node:path'); + // Discover beside the real CLI, just as nodeatomic does through PATH. + const directory = dirname(realpathSync(process.argv[2])); + const manifest = JSON.parse(readFileSync(join(directory, 'libatomic-runtime.json'))); + assert.equal(manifest.platform, process.platform); + assert.equal(manifest.arch, process.arch); + assert.ok(Number(process.versions.napi) >= manifest.nodeApiVersion); + const addon = { exports: {} }; + process.dlopen(addon, join(directory, manifest.library)); + assert.equal(typeof addon.exports.call, 'function'); + assert.equal(typeof addon.exports.descriptor, 'function'); + const descriptor = addon.exports.descriptor(); + assert.ok(Buffer.isBuffer(descriptor) && descriptor.length > 0); + assert.equal(createHash('sha256').update(descriptor).digest('hex'), manifest.descriptorSha256); + console.log('Installed Atomic Node-API runtime loaded and verified'); + JS + assert_match "runtime loaded and verified", shell_output("node #{testpath}/runtime.cjs #{bin}/atomic") end end diff --git a/README.md b/README.md index 391cb1a..81c2b81 100644 --- a/README.md +++ b/README.md @@ -29,16 +29,51 @@ After installation, `brew upgrade atomic` also works in normal Homebrew setups. atomic --version ``` +To exercise the installed Node-API library as well (Node is a test-only dependency): + +```bash +brew install --only-dependencies --include-test atomicdotdev/tap/atomic +brew test atomicdotdev/tap/atomic +``` + ## What this tap installs -A binary build of the Atomic CLI, downloaded from the official [GitHub release](https://github.com/atomicdotdev/atomic/releases). The tap covers four platforms: +A binary build of the Atomic CLI, downloaded from the official [GitHub release](https://github.com/atomicdotdev/atomic/releases). Native runtime availability follows the upstream release targets: + +| OS | Architecture | Node-API runtime | +|---|---|---| +| macOS | Apple Silicon (aarch64) | Included | +| macOS | Intel (x86_64) | CLI only | +| Linux | x86_64 | Included | +| Linux | aarch64 | CLI only | -| OS | Architecture | -|---|---| -| macOS | Apple Silicon (aarch64) | -| macOS | Intel (x86_64) | -| Linux | x86_64 | -| Linux | aarch64 | +On native-runtime platforms, the formula installs `atomic`, the platform library +(`libatomic.dylib` or `libatomic.so`), and `libatomic-runtime.json` together under +`libexec`. The public `bin/atomic` is a symlink to that executable. nodeatomic +follows the symlink and discovers the adjacent library and manifest; no library +is built or downloaded separately. A missing or inconsistent runtime bundle +fails installation rather than silently installing only the CLI on these hosts. + +Homebrew can rewrite library linkage and re-sign Mach-O binaries. The formula +refreshes the manifest's library checksum after that processing, while retaining +the release's protobuf descriptor fingerprint. The formula test loads the library +in Node and checks that fingerprint against the actual exported descriptor. + +The installed runtime must match the protobuf contract expected by its consumer, +including Atomic Sherpa. Installing a complete older runtime does not make it +compatible with a newer consumer. A matching runtime release is still required. + +Ensure the Homebrew `atomic` is the active executable (`type -a atomic`). An +explicit runtime override or a runtime registered by another installer takes +precedence over PATH discovery. To select this installation explicitly on a +supported native-runtime platform, set the following before launching the editor: + +```bash +export ATOMIC_RUNTIME_DIR="$(brew --prefix atomicdotdev/tap/atomic)/libexec" +``` + +Unset any conflicting `LIBATOMIC_ADDON` override. GUI-launched editors may not +inherit shell exports; configure the extension-host environment accordingly. For Windows, download the `.zip` directly from the [release page](https://github.com/atomicdotdev/atomic/releases/latest). @@ -52,6 +87,10 @@ curl -sSf https://atomic.storage/install.sh | sh See the [Atomic installation docs](https://docs.atomic.dev/getting-started/installation) for all options. +nodeatomic and Atomic Sherpa require a matching native library and runtime +manifest, not just the CLI. Verify that an alternative installation provides +the complete runtime before using those consumers. + ## How updates work `Formula/atomic.rb` is kept at the latest release automatically: the @@ -61,10 +100,23 @@ and its `checksums-sha256.txt`, and commits the new version and hashes when they differ. No secrets are involved — the release is public and the workflow commits with its own token. -To run it by hand, or after a release lands: +Installation-layout fixes use a formula revision so existing installations +upgrade even when the upstream version is unchanged. The updater preserves +that revision for same-version updates and removes it when moving to a new +upstream version. + +The [Test tap](.github/workflows/test.yml) workflow runs updater regressions and +installs/tests the formula on macOS and Linux. To run the updater regressions +locally with Minitest installed: ```bash -brew tap atomicdotdev/tap +ruby scripts/update_formula_test.rb +``` + +To pick up a published formula update: + +```bash +brew update brew upgrade atomicdotdev/tap/atomic ``` diff --git a/scripts/update_formula.rb b/scripts/update_formula.rb index 17e147d..561338e 100644 --- a/scripts/update_formula.rb +++ b/scripts/update_formula.rb @@ -70,6 +70,11 @@ def get(url) exit 1 end +# A new upstream version starts at revision zero; same-version updates retain +# the tap's revision so an installation-layout fix still triggers upgrades. +current_version = original[%r{/releases/download/v([^/]+)/}, 1] +formula = formula.sub(/^ revision \d+\n/, "") if current_version != version + if formula == original puts "formula already at #{version}; nothing to do" exit 0 diff --git a/scripts/update_formula_test.rb b/scripts/update_formula_test.rb new file mode 100644 index 0000000..c2adb97 --- /dev/null +++ b/scripts/update_formula_test.rb @@ -0,0 +1,79 @@ +# frozen_string_literal: true + +require "digest" +require "json" +require "minitest/autorun" +require "open3" +require "rbconfig" +require "tmpdir" + +class UpdateFormulaTest < Minitest::Test + ROOT = File.expand_path("..", __dir__) + ORIGINAL = File.read(File.join(ROOT, "Formula/atomic.rb")) + VERSION = ORIGINAL[%r{/releases/download/v([^/]+)/}, 1] + ASSETS = ORIGINAL.scan(%r{/releases/download/v[^/]+/([^"\n]+)}).flatten.freeze + + def update(version:, checksums: nil, formula: ORIGINAL) + Dir.mktmpdir("atomic-formula-test-") do |directory| + path = File.join(directory, "atomic.rb") + File.write(path, formula) + checksums ||= ASSETS.map { |asset| "#{Digest::SHA256.hexdigest(asset)} #{asset}" }.join("\n") + api = { + "https://api.github.com/repos/atomicdotdev/atomic/releases/latest" => JSON.generate( + "tag_name" => "v#{version}", + "assets" => [{ "name" => "checksums-sha256.txt", "browser_download_url" => "https://fixture.invalid/checksums" }] + ), + "https://fixture.invalid/checksums" => checksums + } + fixture = File.join(directory, "api.json") + File.write(fixture, JSON.generate(api)) + interceptor = File.join(directory, "api.rb") + File.write(interceptor, <<~RUBY) + require "json" + require "open-uri" + require "stringio" + def OpenURI.open_uri(url, *) + StringIO.new(JSON.parse(File.read(ENV.fetch("RELEASE_FIXTURE"))).fetch(url.to_s)) + end + RUBY + stdout, stderr, status = Open3.capture3( + { "FORMULA_PATH" => path, "RELEASE_FIXTURE" => fixture, "GITHUB_TOKEN" => nil }, + RbConfig.ruby, "-r", interceptor, File.join(ROOT, "scripts/update_formula.rb") + ) + [File.read(path), stdout, stderr, status] + end + end + + def test_new_release_resets_revision_and_updates_every_platform + result, _, stderr, status = update(version: "99.0.0") + assert status.success?, stderr + refute_match(/^ revision /, result) + ASSETS.each do |asset| + assert_includes result, "/releases/download/v99.0.0/#{asset}" + assert_includes result, Digest::SHA256.hexdigest(asset) + end + end + + def test_same_version_checksum_update_preserves_revision + result, _, stderr, status = update(version: VERSION) + assert status.success?, stderr + assert_equal ORIGINAL[/^ revision \d+/], result[/^ revision \d+/] + ASSETS.each { |asset| assert_includes result, Digest::SHA256.hexdigest(asset) } + end + + def test_current_formula_is_unchanged + checksums = ORIGINAL.scan(%r{/releases/download/v[^/]+/([^"\n]+)"\s+sha256 "([0-9a-f]{64})"}) + .map { |asset, digest| "#{digest} #{asset}" }.join("\n") + result, stdout, stderr, status = update(version: VERSION, checksums: checksums) + assert status.success?, stderr + assert_equal ORIGINAL, result + assert_includes stdout, "nothing to do" + end + + def test_missing_platform_checksum_does_not_modify_formula + result, _, stderr, status = update(version: "99.0.0", checksums: "") + refute status.success? + assert_includes stderr, "missing checksums" + assert_equal ORIGINAL, result + end +end From 3e6648abac6e56e1473ecac6b05594d5b3801e1a Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Mon, 9 Nov 2026 12:55:12 -0600 Subject: [PATCH 2/4] Fix Homebrew setup action reference --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ee417f4..d92ae17 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -27,7 +27,7 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 - - uses: Homebrew/actions/setup-homebrew@master + - uses: Homebrew/actions/setup-homebrew@main - name: Tap checked-out formula run: brew tap --custom-remote atomicdotdev/tap "$GITHUB_WORKSPACE" - name: Install complete release runtime From 268570e49cebd102c3f5dea3ad57f8194936c389 Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Mon, 9 Nov 2026 12:59:35 -0600 Subject: [PATCH 3/4] Document supported Homebrew CI setup --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 81c2b81..82c6735 100644 --- a/README.md +++ b/README.md @@ -106,8 +106,10 @@ that revision for same-version updates and removes it when moving to a new upstream version. The [Test tap](.github/workflows/test.yml) workflow runs updater regressions and -installs/tests the formula on macOS and Linux. To run the updater regressions -locally with Minitest installed: +installs/tests the formula on macOS and Linux, using +`Homebrew/actions/setup-homebrew@main` to prepare the test environment. + +To run the updater regressions locally with Minitest installed: ```bash ruby scripts/update_formula_test.rb From ad820ec05045a7d299535e4bf88a8bef7879da21 Mon Sep 17 00:00:00 2001 From: Bradley Hilton Date: Thu, 12 Nov 2026 13:08:45 -0600 Subject: [PATCH 4/4] fix: ship the complete Atomic v0.22.0 runtime --- Formula/atomic.rb | 16 ++++++++-------- README.md | 4 ++++ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/Formula/atomic.rb b/Formula/atomic.rb index 775b4f3..57b7185 100644 --- a/Formula/atomic.rb +++ b/Formula/atomic.rb @@ -31,21 +31,21 @@ class Atomic < Formula on_macos do if Hardware::CPU.arm? - url "https://github.com/atomicdotdev/atomic/releases/download/v0.21.0/atomic-aarch64-apple-darwin.tar.gz" - sha256 "e9ca65bb0527cb68b94cc7bb74d7f3c9dadfebba54deccb3e0effca049a25fa8" + url "https://github.com/atomicdotdev/atomic/releases/download/v0.22.0/atomic-aarch64-apple-darwin.tar.gz" + sha256 "5ef90e48318eb25ee7f144de4c313eaa7a90fd3587fec81aafa7ddb9431a827e" else - url "https://github.com/atomicdotdev/atomic/releases/download/v0.21.0/atomic-x86_64-apple-darwin.tar.gz" - sha256 "ead9165bc5a2bb3bdab1eb8f624be1da15c4ac6eda1391aa700bfccc9e1f8bdf" + url "https://github.com/atomicdotdev/atomic/releases/download/v0.22.0/atomic-x86_64-apple-darwin.tar.gz" + sha256 "8c560d14590331cd36d7dde0a1e339ad33ee9f08df85c5e47134c28ee3b83c4b" end end on_linux do if Hardware::CPU.arm? - url "https://github.com/atomicdotdev/atomic/releases/download/v0.21.0/atomic-aarch64-unknown-linux-gnu.tar.gz" - sha256 "d8950600d3d832308ea684e0a9ec335dd83835face929872cfd1d25dca80440a" + url "https://github.com/atomicdotdev/atomic/releases/download/v0.22.0/atomic-aarch64-unknown-linux-gnu.tar.gz" + sha256 "947fd893f6b1b4ffb6f55e09fbc3235dbc5e671b1587508bae190bb5f6586385" else - url "https://github.com/atomicdotdev/atomic/releases/download/v0.21.0/atomic-x86_64-unknown-linux-gnu.tar.gz" - sha256 "62fe490fb2a657ddb5c048b78c23ad2ace170eef14709d337f8fbd10b973433e" + url "https://github.com/atomicdotdev/atomic/releases/download/v0.22.0/atomic-x86_64-unknown-linux-gnu.tar.gz" + sha256 "f08a03a712d97b69ff3d23dc11090d5ee149b9da87a3faa74d25de82167abfcc" end end diff --git a/README.md b/README.md index 82c6735..fcdf92a 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,10 @@ The installed runtime must match the protobuf contract expected by its consumer, including Atomic Sherpa. Installing a complete older runtime does not make it compatible with a newer consumer. A matching runtime release is still required. +The current complete-runtime formula targets **Atomic v0.22.0**. It retains +formula revision 1 so existing CLI-only v0.22.0 installations upgrade to the +complete runtime layout. + Ensure the Homebrew `atomic` is the active executable (`type -a atomic`). An explicit runtime override or a runtime registered by another installer takes precedence over PATH discovery. To select this installation explicitly on a