@withautonomi/ant 0.3.8

package/README.md

@@ -0,0 +1,98 @@
+# ant
+
+The unified CLI for the [Autonomi](https://autonomi.com) network: store and retrieve data, and
+manage local nodes.
+
+This package distributes the same signed binary published on the
+[ant-client releases page](https://github.com/WithAutonomi/ant-client/releases). It exists so
+that `ant` can be installed anywhere npm reaches — including agent sandboxes and CI runners that
+allow package-manager traffic but block direct binary downloads.
+
+## Install
+
+```sh
+npm install -g @withautonomi/ant
+ant --help
+```
+
+The beta channel tracks pre-release builds:
+
+```sh
+npm install -g @withautonomi/ant@beta
+```
+
+## Supported platforms
+
+| Platform | Architecture |
+|---|---|
+| Linux | x86_64, ARM64 |
+| macOS | x86_64, Apple silicon |
+| Windows | x86_64 (also used on ARM64, under emulation) |
+
+Linux builds are statically linked against musl, so they run on any distribution.
+
+The binary lives in a per-platform companion package (`@withautonomi/ant-linux-x64` and friends)
+declared as an optional dependency, so `npm install` downloads only the one your machine needs.
+Installing with `--no-optional` or `--omit=optional` skips it and leaves `ant` unable to run.
+
+## Configuration
+
+`ant` joins the network through a list of bootstrap peers. It works out of the box: the same
+peer list published in the release archives is compiled into the binary, and is used whenever no
+config file is present.
+
+To customise the list, put your own `bootstrap_peers.toml` here — it takes precedence over the
+built-in one:
+
+| Platform | Path |
+|---|---|
+| Linux | `$XDG_CONFIG_HOME/ant/bootstrap_peers.toml`, or `~/.config/ant/bootstrap_peers.toml` |
+| macOS | `~/Library/Application Support/ant/bootstrap_peers.toml` |
+| Windows | `%APPDATA%\ant\bootstrap_peers.toml` |
+
+Installing normally writes that file for you, but npm 12 blocks package install scripts by
+default, so it often will not appear. Nothing breaks when it doesn't. If you want the file so you
+can edit it, either install with
+
+```sh
+npm install -g --allow-scripts=@withautonomi/ant @withautonomi/ant
+```
+
+or copy it out of the installed platform package. Individual runs can always override everything
+with `ant -b <multiaddr> …`.
+
+## Updating
+
+```sh
+npm update -g @withautonomi/ant
+```
+
+`ant update`, which self-replaces the binary for installs made from the release page, detects an
+npm-managed install and tells you to use npm instead — otherwise npm's view of the installed
+version would silently diverge from what is on disk, and the next `npm update` would roll you
+back.
+
+## Uninstall
+
+```sh
+npm uninstall -g @withautonomi/ant
+```
+
+Your config directory is left alone. Delete it by hand if you want it gone.
+
+## Verifying what you installed
+
+Packages are published from the ant-client release workflow with
+[npm provenance](https://docs.npmjs.com/generating-provenance-statements), so npm records which
+workflow run and commit produced each tarball. The binaries are copied verbatim from the release
+archives, whose checksums and ML-DSA-65 signatures are verified during packaging, so they are
+byte-identical to the corresponding GitHub release assets.
+
+## Other install methods
+
+The release page, `install.sh` and `install.ps1` all still work and are unaffected by this
+package. See the [project README](https://github.com/WithAutonomi/ant-client#readme).
+
+## Licence
+
+MIT OR Apache-2.0

package/bin/ant.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict';
+
+// Launcher for the `ant` binary installed by the matching platform package.
+//
+// A postinstall script could copy the binary here and let npm exec it directly, saving this
+// process. It is deliberately not done that way: `npm install --ignore-scripts` is common in
+// agent sandboxes and locked-down CI, and this package must work there. A JS launcher always
+// runs, at the cost of Node's startup — negligible for a network-bound CLI.
+
+const { spawnSync } = require('node:child_process');
+const {
+  binaryPath,
+  packageName,
+  platformKey,
+  supportedPlatforms,
+  ensureExecutable,
+} = require('../lib/resolve.js');
+
+function fail(message) {
+  process.stderr.write(`ant: ${message}\n`);
+  process.exit(1);
+}
+
+const key = platformKey();
+const binary = binaryPath(key);
+
+if (!binary) {
+  const pkg = packageName(key);
+  if (!pkg) {
+    fail(
+      `no prebuilt binary for ${key}.\n` +
+        `  Supported platforms: ${supportedPlatforms().join(', ')}\n` +
+        `  Build from source instead: https://github.com/WithAutonomi/ant-client`
+    );
+  }
+  fail(
+    `the platform package ${pkg} is not installed.\n` +
+      `  Reinstall with:  npm install -g @withautonomi/ant\n` +
+      `  Note that --no-optional and --omit=optional prevent the binary from being fetched.`
+  );
+}
+
+ensureExecutable(binary);
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+
+if (result.error) {
+  fail(`failed to run ${binary}: ${result.error.message}`);
+}
+
+// Re-raise rather than translating to an exit code, so callers see the CLI's own termination
+// reason (a Ctrl-C on a long upload must look like a Ctrl-C to the shell).
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+  // Reached only if the signal is ignored or blocked.
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/lib/resolve.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// Shared platform resolution for the @withautonomi/ant meta package.
+//
+// The meta package carries no binary. Each supported platform has its own package holding the
+// `ant` binary from the matching GitHub release archive, declared as an optionalDependency with
+// `os`/`cpu` guards, so `npm install` fetches exactly one of them. This module answers "which
+// one, and where did npm put it?".
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// `${process.platform}-${process.arch}` -> platform package name.
+//
+// Mirrors the release matrix in .github/workflows/ant-cli-release.yml. If a target is added
+// there, add it here, to PLATFORM_TARGETS in build-packages.sh, and to the optionalDependencies
+// in package.json.tmpl.
+const PACKAGES = {
+  'darwin-arm64': '@withautonomi/ant-darwin-arm64',
+  'darwin-x64': '@withautonomi/ant-darwin-x64',
+  'linux-arm64': '@withautonomi/ant-linux-arm64',
+  'linux-x64': '@withautonomi/ant-linux-x64',
+  'win32-x64': '@withautonomi/ant-win32-x64',
+  // There is no native Windows ARM64 build. install.ps1 hands ARM64 users the x86_64 binary to
+  // run under emulation (install.ps1:160-162); npm does the same, via an extra `arm64` entry in
+  // the win32 package's `cpu` list.
+  'win32-arm64': '@withautonomi/ant-win32-x64',
+};
+
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function packageName(key = platformKey()) {
+  return PACKAGES[key] || null;
+}
+
+function supportedPlatforms() {
+  return Object.keys(PACKAGES).sort();
+}
+
+// Absolute path to the installed platform package, or null if npm did not install one.
+//
+// Resolution is anchored at this file rather than the cwd so it follows the dependency edge from
+// the meta package, which is what npm actually laid out — global installs, local installs and
+// nested node_modules all work out of the same lookup.
+function packageDir(key = platformKey()) {
+  const name = packageName(key);
+  if (!name) return null;
+  try {
+    return path.dirname(require.resolve(`${name}/package.json`, { paths: [__dirname] }));
+  } catch {
+    return null;
+  }
+}
+
+function binaryName() {
+  return process.platform === 'win32' ? 'ant.exe' : 'ant';
+}
+
+// Absolute path to the `ant` executable, or null if it is not installed.
+function binaryPath(key = platformKey()) {
+  const dir = packageDir(key);
+  if (!dir) return null;
+  const file = path.join(dir, 'bin', binaryName());
+  return fs.existsSync(file) ? file : null;
+}
+
+// npm normally preserves the executable bit through pack/publish/install, but registries,
+// mirrors and unusual umasks have all been known to drop it, and `--ignore-scripts` rules out
+// fixing it at install time. Restoring it here costs one stat on a path we are about to exec
+// anyway, and turns an opaque EACCES into a working command.
+function ensureExecutable(file) {
+  if (process.platform === 'win32') return;
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return;
+  } catch {
+    // Not executable — fall through and try to fix it.
+  }
+  try {
+    fs.chmodSync(file, 0o755);
+  } catch {
+    // Best effort. If this fails the spawn below reports the real error.
+  }
+}
+
+module.exports = {
+  PACKAGES,
+  binaryName,
+  binaryPath,
+  ensureExecutable,
+  packageDir,
+  packageName,
+  platformKey,
+  supportedPlatforms,
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@withautonomi/ant",
+  "version": "0.3.8",
+  "description": "Unified CLI (`ant`) for the Autonomi network: store and retrieve data, and manage local nodes.",
+  "keywords": [
+    "autonomi",
+    "ant",
+    "cli",
+    "p2p",
+    "storage",
+    "decentralized"
+  ],
+  "homepage": "https://github.com/WithAutonomi/ant-client#readme",
+  "bugs": {
+    "url": "https://github.com/WithAutonomi/ant-client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WithAutonomi/ant-client.git"
+  },
+  "license": "MIT OR Apache-2.0",
+  "bin": {
+    "ant": "bin/ant.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "postinstall.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@withautonomi/ant-darwin-arm64": "0.3.8",
+    "@withautonomi/ant-darwin-x64": "0.3.8",
+    "@withautonomi/ant-linux-arm64": "0.3.8",
+    "@withautonomi/ant-linux-x64": "0.3.8",
+    "@withautonomi/ant-win32-x64": "0.3.8"
+  }
+}

package/postinstall.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// Installs bootstrap_peers.toml into the platform config directory.
+//
+// Deliberately mirrors install.sh:216-224 and install.ps1:189-198: same destination, and the
+// file is written only when absent so a user's edited peer list is never overwritten. The
+// source is the copy inside the platform package, which came verbatim from the release archive,
+// so an npm install and an install.sh install leave the same bytes in the same place.
+//
+// ant-core only ever reads this file, never writes it. It is not required, though: npm 12
+// blocks install scripts by default (and `--ignore-scripts` does the same on older npm), so this
+// frequently does not run, and config::resolve_bootstrap_multiaddrs falls back to the seeds
+// compiled into the binary rather than failing with NoBootstrapPeers. What this script adds is a
+// real file the user can find and edit. See npm/README.md.
+//
+// This script must never fail the install. npm treats a non-zero postinstall as a failed
+// install, and a missing peers file is recoverable while a failed install is not.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { packageDir } = require('./lib/resolve.js');
+
+const CONFIG_FILE = 'bootstrap_peers.toml';
+
+function say(message) {
+  process.stdout.write(`@withautonomi/ant: ${message}\n`);
+}
+
+function warn(message) {
+  process.stderr.write(`@withautonomi/ant: ${message}\n`);
+}
+
+// Mirrors config_dir() in install.sh:59-67, Get-ConfigDir in install.ps1:149-151, and
+// ant_core::config::config_dir() in ant-core/src/config.rs:32-45. All four must agree.
+function configDir() {
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA;
+    if (!appData) throw new Error('APPDATA is not set');
+    return path.join(appData, 'ant');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'ant');
+  }
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return path.join(xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), '.config'), 'ant');
+}
+
+function main() {
+  const dir = packageDir();
+  if (!dir) {
+    // No platform package: either an unsupported platform or --no-optional. bin/ant.js explains
+    // it properly when the command is actually run; do not fail the install over it here.
+    return;
+  }
+
+  const source = path.join(dir, CONFIG_FILE);
+  if (!fs.existsSync(source)) {
+    warn(`${CONFIG_FILE} is missing from the platform package; skipping bootstrap config.`);
+    return;
+  }
+
+  const destDir = configDir();
+  const dest = path.join(destDir, CONFIG_FILE);
+
+  if (fs.existsSync(dest)) {
+    say(`bootstrap config already exists at ${dest} - skipping`);
+    return;
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(source, dest);
+  say(`installed bootstrap config to ${dest}`);
+}
+
+try {
+  main();
+} catch (err) {
+  warn(
+    `could not install ${CONFIG_FILE}: ${err.message}\n` +
+      `  ant is installed and usable; supply peers with 'ant -b <multiaddr> ...' or create the\n` +
+      `  file yourself. See https://github.com/WithAutonomi/ant-client#configuration`
+  );
+}