agnostic-ai 0.62.0 → 0.64.1

package/README.md

@@ -13,10 +13,26 @@ Or install it globally:
 npm install -g agnostic-ai
 ```
 
-This package is a thin wrapper: it downloads the prebuilt Go binary for your platform from [GitHub Releases](https://github.com/Chemaclass/agnostic-ai/releases) and runs it. Supported platforms are macOS, Linux, and Windows on x64 and arm64.
+npm is one route of several. The same binary installs through Homebrew on macOS and Linux:
 
-The download normally happens on install. Under npm's install-script gating (`--ignore-scripts`, or npm 11's default prompt), it happens on first run instead. Pin a different binary version with `AGNOSTIC_AI_VERSION=v0.45.0`.
+```bash
+brew install --cask Chemaclass/tap/agnostic-ai
+```
+
+Or through the install script, which needs no package manager:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Chemaclass/agnostic-ai/main/scripts/install.sh | bash
+```
+
+Windows, Go, and manual download are covered in [all install options](https://agnostic-ai.org/docs/installation/).
+
+This package is a thin wrapper around the prebuilt Go binary. The binary ships inside a platform package (`@agnostic-ai/darwin-arm64` and five siblings), declared as optional dependencies. npm reads each one's `os` and `cpu` and installs only the one that matches your machine. Supported platforms are macOS, Linux, and Windows on x64 and arm64.
+
+Nothing is downloaded and no install script runs, so the package works under `--ignore-scripts`, behind a proxy, and from an offline npm mirror. To pin a version, pin the package: `npm install -g agnostic-ai@<version>`.
+
+Set `AGNOSTIC_AI_BINARY` to an absolute path to run a binary this package does not ship, such as one you built yourself.
 
-Full docs, targets, and configuration: [github.com/Chemaclass/agnostic-ai](https://github.com/Chemaclass/agnostic-ai).
+Full docs, targets, and configuration: [agnostic-ai.org](https://agnostic-ai.org).
 
 MIT licensed.

package/bin/agnostic-ai.js

@@ -2,14 +2,80 @@
 'use strict'
 
 const { spawnSync } = require('node:child_process')
-const { ensureBinary } = require('../lib/download')
+const os = require('node:os')
+const path = require('node:path')
+const { entryPoint, packageName, platformFor } = require('../lib/platforms')
 
-async function main() {
+const DOCS = 'https://agnostic-ai.org/docs/installation/'
+
+// A global install resolves its dependencies from the global tree, a project
+// install from the project's, and `npm install` without `-g` only ever writes
+// the second. Telling a globally installed CLI to run the project command
+// leaves it exactly as broken as it was, so the repair hint has to know which
+// tree it is sitting in.
+//
+// npm puts a global package under its own prefix: `<prefix>/lib/node_modules`
+// on macOS and Linux, `<prefix>\node_modules` on Windows, where <prefix> is
+// npm's own directory (commonly `.../npm`). A project install sits in a
+// `node_modules` whose parent is the project. Unrecognised layouts fall back
+// to the project command, which is the common case, and the message names the
+// other form either way.
+function isGlobalInstall(dir) {
+  const parts = path.resolve(dir).split(path.sep)
+  const i = parts.lastIndexOf('node_modules')
+  if (i < 1) return false
+  return parts[i - 1] === 'lib' || parts[i - 1] === 'npm'
+}
+
+// The binary ships inside a platform package that npm installed as an optional
+// dependency, so finding it is a module lookup, not a download. Nothing here
+// touches the network.
+function resolveBinary() {
+  // Escape hatch for a binary this package does not ship: a local build, an
+  // unsupported CPU, an air-gapped machine that already has one on disk.
+  const override = process.env.AGNOSTIC_AI_BINARY
+  if (override) return override
+
+  const platform = platformFor(process.platform, process.arch)
+  if (!platform) {
+    throw new Error(
+      `no prebuilt binary for ${process.platform}/${process.arch}. Build one with ` +
+        '`go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@latest` and point ' +
+        `AGNOSTIC_AI_BINARY at it, or pick another route: ${DOCS}`
+    )
+  }
+
+  try {
+    return require.resolve(entryPoint(platform))
+  } catch {
+    // npm reuses a lockfile written on another platform without re-resolving
+    // optional dependencies, which leaves the matching package absent
+    // (npm/cli#4828). `--no-optional` and `--omit=optional` do the same on
+    // purpose. Both look like a successful install until the CLI runs.
+    //
+    // --include=optional is not decoration: the second cause is an
+    // `omit=optional` sitting in the user's npm config, and a plain reinstall
+    // obeys it and skips the package again.
+    const isGlobal = isGlobalInstall(__dirname)
+    const scope = isGlobal ? 'installed globally' : 'installed in this project'
+    const fix = isGlobal
+      ? 'npm install -g agnostic-ai --force --include=optional'
+      : 'npm install agnostic-ai --force --include=optional'
+    const other = isGlobal ? 'drop -g for a project install' : 'add -g for a global install'
+    throw new Error(
+      `${packageName(platform)} is not installed, so there is no binary to run. npm installs ` +
+        'it as an optional dependency; a lockfile copied from another platform or an install ' +
+        `run with --omit=optional skips it. This copy is ${scope}, so reinstall with ` +
+        `\`${fix}\` (${other}), or set AGNOSTIC_AI_BINARY to a binary you already have. ` +
+        `Other routes: ${DOCS}`
+    )
+  }
+}
+
+function main() {
   let binary
   try {
-    // Normally already on disk from postinstall; this covers an install that
-    // ran with --ignore-scripts or without network.
-    binary = await ensureBinary({ log: (m) => console.error(`agnostic-ai: ${m}`) })
+    binary = resolveBinary()
   } catch (err) {
     console.error(`agnostic-ai: ${err.message}`)
     process.exit(1)
@@ -20,8 +86,12 @@ async function main() {
     console.error(`agnostic-ai: ${result.error.message}`)
     process.exit(1)
   }
-  // A signalled child reports null status; 128+signal is the shell convention.
-  process.exit(result.status === null ? 128 : result.status)
+  // A signalled child reports a null status; 128+signal is the shell
+  // convention, so a caller can tell a SIGINT (130) from a SIGKILL (137).
+  if (result.status === null) {
+    process.exit(128 + (os.constants.signals[result.signal] || 0))
+  }
+  process.exit(result.status)
 }
 
 main()

package/lib/platforms.js

@@ -0,0 +1,64 @@
+'use strict'
+
+// The one table the whole npm distribution reads: the bin shim uses it to find
+// the binary at runtime, scripts/build-platform-packages.js uses it to emit the
+// packages at release time, and the parent package.json pins the same six names
+// in optionalDependencies.
+//
+// Keeping it in one file is the point. npm skips an optional dependency whose
+// `os` or `cpu` does not match the machine, and it skips it silently, so a pair
+// that disagrees with what the shim asks for installs nothing and leaves the CLI
+// missing with no error anywhere. Two copies of this table is how that happens.
+
+// Published under the project's npm organization. The dedicated scope keeps
+// ownership separate from a maintainer account, and makes the project name in
+// each package redundant: `@agnostic-ai/win32-x64` already identifies both.
+const SCOPE = '@agnostic-ai'
+
+const BINARY = 'agnostic-ai'
+
+// `os` and `cpu` are npm's own spellings, matched against process.platform and
+// process.arch. `goos` and `goarch` are Go's, and name the release archive the
+// binary is extracted from. The two vocabularies differ on win32/windows and
+// x64/amd64, which is the mapping this table exists to hold.
+const PLATFORMS = [
+  { os: 'darwin', cpu: 'arm64', goos: 'darwin', goarch: 'arm64' },
+  { os: 'darwin', cpu: 'x64', goos: 'darwin', goarch: 'amd64' },
+  { os: 'linux', cpu: 'arm64', goos: 'linux', goarch: 'arm64' },
+  { os: 'linux', cpu: 'x64', goos: 'linux', goarch: 'amd64' },
+  { os: 'win32', cpu: 'arm64', goos: 'windows', goarch: 'arm64' },
+  { os: 'win32', cpu: 'x64', goos: 'windows', goarch: 'amd64' },
+]
+
+function packageName(platform) {
+  return `${SCOPE}/${platform.os}-${platform.cpu}`
+}
+
+function binaryName(platform) {
+  return platform.os === 'win32' ? `${BINARY}.exe` : BINARY
+}
+
+// What the shim hands require.resolve(). A subpath of the platform package, so
+// Node walks the same node_modules lookup npm just populated.
+function entryPoint(platform) {
+  return `${packageName(platform)}/${binaryName(platform)}`
+}
+
+function platformFor(nodeOs, nodeCpu) {
+  return PLATFORMS.find((p) => p.os === nodeOs && p.cpu === nodeCpu)
+}
+
+// Exact pins, never a range. A platform package carries a binary built from one
+// commit, so a caret would let npm pair a new CLI with an old binary.
+function optionalDependencies(version) {
+  return Object.fromEntries(PLATFORMS.map((p) => [packageName(p), version]))
+}
+
+module.exports = {
+  PLATFORMS,
+  binaryName,
+  entryPoint,
+  optionalDependencies,
+  packageName,
+  platformFor,
+}

package/package.json

@@ -1,19 +1,30 @@
 {
   "name": "agnostic-ai",
-  "version": "0.62.0",
+  "version": "0.64.1",
   "description": "One spec, every AI CLI. Sync agents, skills, rules, hooks, and MCP servers to Claude Code, Codex, Gemini, Cursor, Copilot, and 20 more.",
   "keywords": [
     "ai",
     "cli",
+    "agents",
+    "skills",
+    "rules",
+    "hooks",
+    "mcp",
+    "prompts",
+    "agents-md",
     "claude",
+    "claude-code",
     "codex",
     "cursor",
     "copilot",
-    "agents",
-    "skills",
-    "mcp"
+    "gemini",
+    "windsurf",
+    "cline",
+    "opencode",
+    "ai-tools",
+    "developer-tools"
   ],
-  "homepage": "https://github.com/Chemaclass/agnostic-ai#readme",
+  "homepage": "https://agnostic-ai.org",
   "bugs": {
     "url": "https://github.com/Chemaclass/agnostic-ai/issues"
   },
@@ -28,25 +39,22 @@
     "agnostic-ai": "bin/agnostic-ai.js"
   },
   "files": [
-    "bin/",
-    "lib/",
-    "scripts/",
+    "bin/agnostic-ai.js",
+    "lib/platforms.js",
     "README.md"
   ],
   "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "test": "node lib/download_test.js"
+    "test": "node lib/platforms_test.js && node scripts/build-platform-packages_test.js"
   },
   "engines": {
     "node": ">=18"
   },
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
-  "cpu": [
-    "x64",
-    "arm64"
-  ]
+  "optionalDependencies": {
+    "@agnostic-ai/darwin-arm64": "0.64.1",
+    "@agnostic-ai/darwin-x64": "0.64.1",
+    "@agnostic-ai/linux-arm64": "0.64.1",
+    "@agnostic-ai/linux-x64": "0.64.1",
+    "@agnostic-ai/win32-arm64": "0.64.1",
+    "@agnostic-ai/win32-x64": "0.64.1"
+  }
 }

package/lib/download.js

@@ -1,122 +0,0 @@
-'use strict'
-
-// Fetches the agnostic-ai release binary for the current platform. Shared by
-// the postinstall hook and the bin shim, so a failed install still recovers on
-// first run instead of leaving a broken command.
-
-const { execFileSync } = require('node:child_process')
-const crypto = require('node:crypto')
-const fs = require('node:fs')
-const https = require('node:https')
-const os = require('node:os')
-const path = require('node:path')
-
-const REPO = 'Chemaclass/agnostic-ai'
-const BINARY = process.platform === 'win32' ? 'agnostic-ai.exe' : 'agnostic-ai'
-
-const PLATFORMS = { darwin: 'darwin', linux: 'linux', win32: 'windows' }
-const ARCHS = { x64: 'amd64', arm64: 'arm64' }
-
-function target() {
-  const goos = PLATFORMS[process.platform]
-  const goarch = ARCHS[process.arch]
-  if (!goos || !goarch) {
-    throw new Error(
-      `agnostic-ai has no prebuilt binary for ${process.platform}/${process.arch}. ` +
-        'Build from source: go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@latest'
-    )
-  }
-  return { goos, goarch, ext: goos === 'windows' ? 'zip' : 'tar.gz' }
-}
-
-function assetName() {
-  const { goos, goarch, ext } = target()
-  return `agnostic-ai_${goos}_${goarch}.${ext}`
-}
-
-function binaryPath() {
-  return path.join(__dirname, '..', 'bin', BINARY)
-}
-
-function get(url) {
-  return new Promise((resolve, reject) => {
-    https
-      .get(url, { headers: { 'user-agent': 'agnostic-ai-npm' } }, (res) => {
-        // GitHub redirects release assets to a signed object-store URL.
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          res.resume()
-          resolve(get(res.headers.location))
-          return
-        }
-        if (res.statusCode !== 200) {
-          res.resume()
-          reject(new Error(`GET ${url} failed with HTTP ${res.statusCode}`))
-          return
-        }
-        const chunks = []
-        res.on('data', (c) => chunks.push(c))
-        res.on('end', () => resolve(Buffer.concat(chunks)))
-        res.on('error', reject)
-      })
-      .on('error', reject)
-  })
-}
-
-// The published package carries the release version; a checkout carries the
-// 0.0.0-dev placeholder, which has no matching release, so fall back to latest.
-async function resolveVersion() {
-  if (process.env.AGNOSTIC_AI_VERSION) return process.env.AGNOSTIC_AI_VERSION
-
-  const { version } = require('../package.json')
-  if (version && !version.startsWith('0.0.0')) return `v${version}`
-
-  const body = await get(`https://api.github.com/repos/${REPO}/releases/latest`)
-  const tag = JSON.parse(body.toString('utf8')).tag_name
-  if (!tag) throw new Error('could not resolve the latest agnostic-ai release')
-  return tag
-}
-
-function downloadUrl(version, asset) {
-  return `https://github.com/${REPO}/releases/download/${version}/${asset}`
-}
-
-async function verifyChecksum(archive, asset, version) {
-  const sums = (await get(downloadUrl(version, 'checksums.txt'))).toString('utf8')
-  const line = sums.split('\n').find((l) => l.trim().endsWith(asset))
-  if (!line) throw new Error(`${asset} missing from checksums.txt`)
-
-  const expected = line.trim().split(/\s+/)[0]
-  const actual = crypto.createHash('sha256').update(fs.readFileSync(archive)).digest('hex')
-  if (actual !== expected) throw new Error(`checksum mismatch for ${asset}`)
-}
-
-async function ensureBinary({ log = () => {} } = {}) {
-  const dest = binaryPath()
-  if (fs.existsSync(dest)) return dest
-
-  const version = await resolveVersion()
-  const asset = assetName()
-  log(`downloading agnostic-ai ${version} (${asset})`)
-
-  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'agnostic-ai-'))
-  try {
-    const archive = path.join(work, asset)
-    fs.writeFileSync(archive, await get(downloadUrl(version, asset)))
-    await verifyChecksum(archive, asset, version)
-
-    // bsdtar reads both tar.gz and zip, and ships with macOS and Windows 10
-    // 1803+; Linux only ever gets the tar.gz here, so GNU tar is fine too.
-    execFileSync('tar', ['-xf', archive, '-C', work, BINARY], { stdio: 'ignore' })
-
-    fs.mkdirSync(path.dirname(dest), { recursive: true })
-    fs.copyFileSync(path.join(work, BINARY), dest)
-    fs.chmodSync(dest, 0o755)
-  } finally {
-    fs.rmSync(work, { recursive: true, force: true })
-  }
-
-  log(`installed ${dest}`)
-  return dest
-}
-
-module.exports = { assetName, binaryPath, downloadUrl, ensureBinary, resolveVersion, target }

package/lib/download_test.js

@@ -1,62 +0,0 @@
-'use strict'
-
-// Run: node npm/lib/download_test.js  (or npm test inside npm/)
-//
-// Covers the pure mapping logic. The download path itself is exercised
-// end to end by .github/workflows/install.yml against a real release.
-
-const assert = require('node:assert')
-const path = require('node:path')
-const { assetName, binaryPath, downloadUrl, resolveVersion, target } = require('./download')
-
-const tests = {
-  'asset name matches the release archive for this platform'() {
-    const { goos, goarch } = target()
-    const expected = goos === 'windows'
-      ? `agnostic-ai_${goos}_${goarch}.zip`
-      : `agnostic-ai_${goos}_${goarch}.tar.gz`
-    assert.strictEqual(assetName(), expected)
-  },
-
-  'windows gets a zip, every other platform a tar.gz'() {
-    assert.strictEqual(target().ext, process.platform === 'win32' ? 'zip' : 'tar.gz')
-  },
-
-  'download url points at the tagged release asset'() {
-    assert.strictEqual(
-      downloadUrl('v0.45.0', 'agnostic-ai_linux_amd64.tar.gz'),
-      'https://github.com/Chemaclass/agnostic-ai/releases/download/v0.45.0/agnostic-ai_linux_amd64.tar.gz'
-    )
-  },
-
-  'binary path lands in the package bin dir'() {
-    assert.strictEqual(path.dirname(binaryPath()), path.join(__dirname, '..', 'bin'))
-    assert.match(path.basename(binaryPath()), /^agnostic-ai(\.exe)?$/)
-  },
-
-  async 'env override wins over the package version'() {
-    process.env.AGNOSTIC_AI_VERSION = 'v1.2.3'
-    try {
-      assert.strictEqual(await resolveVersion(), 'v1.2.3')
-    } finally {
-      delete process.env.AGNOSTIC_AI_VERSION
-    }
-  },
-}
-
-async function run() {
-  let failed = 0
-  for (const [name, fn] of Object.entries(tests)) {
-    try {
-      await fn()
-      console.log(`ok   ${name}`)
-    } catch (err) {
-      failed++
-      console.error(`FAIL ${name}\n     ${err.message}`)
-    }
-  }
-  console.log(`\n${Object.keys(tests).length - failed} passed, ${failed} failed`)
-  process.exit(failed === 0 ? 0 : 1)
-}
-
-run()

package/scripts/postinstall.js

@@ -1,12 +0,0 @@
-'use strict'
-
-// Downloads the binary at install time. A failure here is a warning, never an
-// install error: the bin shim retries on first run, so an offline install or a
-// blocked proxy does not break `npm install` for the whole project.
-
-const { ensureBinary } = require('../lib/download')
-
-ensureBinary({ log: (m) => console.log(`agnostic-ai: ${m}`) }).catch((err) => {
-  console.warn(`agnostic-ai: ${err.message}`)
-  console.warn('agnostic-ai: the binary will be fetched on first run instead')
-})