Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
36 changes: 36 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -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@main
- 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
93 changes: 81 additions & 12 deletions Formula/atomic.rb
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -17,41 +20,107 @@ 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"
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

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
76 changes: 67 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,55 @@ 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 |

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.

| OS | Architecture |
|---|---|
| macOS | Apple Silicon (aarch64) |
| macOS | Intel (x86_64) |
| Linux | x86_64 |
| Linux | aarch64 |
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.

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
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).

Expand All @@ -52,6 +91,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
Expand All @@ -61,10 +104,25 @@ 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, using
`Homebrew/actions/setup-homebrew@main` to prepare the test environment.

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
```

Expand Down
5 changes: 5 additions & 0 deletions scripts/update_formula.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
79 changes: 79 additions & 0 deletions scripts/update_formula_test.rb
Original file line number Diff line number Diff line change
@@ -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
Loading