agnostic-ai 0.62.0 → 0.63.0

package/README.md

@@ -13,10 +13,24 @@ Or install it globally:
 npm install -g agnostic-ai
 ```
 
+npm is one route of several. The same binary installs through Homebrew on macOS and Linux:
+
+```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: 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.
 
-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`.
+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. Set `AGNOSTIC_AI_VERSION` to any [release tag](https://github.com/Chemaclass/agnostic-ai/releases) to pin a different binary.
 
-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,6 +2,7 @@
 'use strict'
 
 const { spawnSync } = require('node:child_process')
+const os = require('node:os')
 const { ensureBinary } = require('../lib/download')
 
 async function main() {
@@ -20,8 +21,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/download.js

@@ -7,6 +7,7 @@
 const { execFileSync } = require('node:child_process')
 const crypto = require('node:crypto')
 const fs = require('node:fs')
+const http = require('node:http')
 const https = require('node:https')
 const os = require('node:os')
 const path = require('node:path')
@@ -17,6 +18,17 @@ const BINARY = process.platform === 'win32' ? 'agnostic-ai.exe' : 'agnostic-ai'
 const PLATFORMS = { darwin: 'darwin', linux: 'linux', win32: 'windows' }
 const ARCHS = { x64: 'amd64', arm64: 'arm64' }
 
+// GitHub redirects a release asset to object storage exactly once, so five hops
+// is slack for a proxy in the way while still ending a redirect loop.
+const MAX_REDIRECTS = 5
+
+// Silence, not slowness, is what this catches: the archives are a few MB, so 30
+// seconds without a single byte means the connection is wedged. Left unbounded,
+// the OS connect timeout alone runs to 75 seconds, and a server that accepts and
+// never answers never times out at all. This runs inside postinstall, where a
+// stall blocks `npm install` for the whole project.
+const TIMEOUT_MS = 30_000
+
 function target() {
   const goos = PLATFORMS[process.platform]
   const goarch = ARCHS[process.arch]
@@ -38,42 +50,151 @@ function binaryPath() {
   return path.join(__dirname, '..', 'bin', BINARY)
 }
 
-function get(url) {
+// Node throws an AggregateError with an empty `message` when a host resolves to
+// several addresses and every connection fails, which is the ordinary shape of
+// github.com behind a firewall. Printing `err.message` then prints nothing, so
+// rebuild a message out of what the error does carry.
+function describeError(err) {
+  if (!err || err.message) return err
+
+  const codes = new Set()
+  const causes = new Set()
+  if (err.code) codes.add(err.code)
+  for (const cause of Array.isArray(err.errors) ? err.errors : []) {
+    if (!cause) continue
+    if (cause.code) codes.add(cause.code)
+    if (cause.message) causes.add(cause.message)
+  }
+
+  const summary = codes.size ? [...codes].join(', ') : `${err.name || 'Error'} with no message`
+  const described = new Error(causes.size ? `${summary}: ${[...causes].join('; ')}` : summary)
+  described.cause = err
+  return described
+}
+
+function client(url) {
+  if (url.startsWith('https:')) return https
+  // Only reachable through a redirect; kept so a plain http hop reports
+  // something readable instead of ERR_INVALID_PROTOCOL.
+  if (url.startsWith('http:')) return http
+  throw new Error(`GET ${url} uses an unsupported protocol`)
+}
+
+// Resolves once the response headers are in, with a `body()` that reads the
+// rest. Splitting it that way lets a caller act on the headers alone, and keeps
+// the one timeout covering both halves: the socket timeout fires on silence
+// whether or not the body has started, and a request torn down by it must
+// report the timeout rather than the `aborted` the stream raises in its wake.
+function request(url, timeoutMs) {
   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)
+    let timedOut = null
+    const fail = (err) => reject(timedOut || describeError(err))
+
+    const req = client(url)
+      .get(url, { headers: { 'user-agent': 'agnostic-ai-npm' }, timeout: timeoutMs }, (res) => {
+        resolve({
+          res,
+          body: () =>
+            new Promise((done, failBody) => {
+              const chunks = []
+              res.on('data', (c) => chunks.push(c))
+              res.on('end', () => done(Buffer.concat(chunks)))
+              res.on('error', (err) => failBody(timedOut || describeError(err)))
+            }),
+        })
+      })
+      .on('timeout', () => {
+        // The socket timeout only raises the event; the request has to be torn
+        // down by hand, and destroy(err) is what surfaces as a rejection.
+        timedOut = new Error(`GET ${url} timed out after ${timeoutMs / 1000}s of silence`)
+        req.destroy(timedOut)
       })
-      .on('error', reject)
+      .on('error', fail)
   })
 }
 
+// Drain a response nobody will read. The listener is not optional: a response
+// that errors with nothing attached takes the whole process down.
+function discard(res) {
+  res.resume()
+  res.on('error', () => {})
+}
+
+function redirectTo(res) {
+  const { statusCode, headers } = res
+  return statusCode >= 300 && statusCode < 400 && headers.location ? headers.location : ''
+}
+
+async function get(url, { redirects = 0, timeoutMs = TIMEOUT_MS } = {}) {
+  const { res, body } = await request(url, timeoutMs)
+
+  // GitHub redirects release assets to a signed object-store URL.
+  const next = redirectTo(res)
+  if (next) {
+    discard(res)
+    if (redirects >= MAX_REDIRECTS) {
+      throw new Error(`GET ${url} still redirecting after ${MAX_REDIRECTS} hops`)
+    }
+    if (url.startsWith('https:') && next.startsWith('http:')) {
+      throw new Error(`GET ${url} redirects to plain http (${next}); refusing`)
+    }
+    return get(next, { redirects: redirects + 1, timeoutMs })
+  }
+
+  if (res.statusCode !== 200) {
+    discard(res)
+    throw new Error(`GET ${url} failed with HTTP ${res.statusCode}`)
+  }
+  return body()
+}
+
+// Release tags carry the `v`, but `npm view` and package.json print the bare
+// number, so both spellings of AGNOSTIC_AI_VERSION have to reach the same tag.
+// Anything that does not start with a digit is passed through untouched.
+function releaseTag(version) {
+  const trimmed = version.trim()
+  return /^\d/.test(trimmed) ? `v${trimmed}` : trimmed
+}
+
+// `releases/latest` on github.com answers 302 to the tag page, so the tag is in
+// the Location header. That keeps release resolution off api.github.com, which
+// allows 60 unauthenticated requests an hour per IP: a shared CI address burns
+// through that and every install then fails with HTTP 403 (#940). The redirect
+// target is what this wants, so it reads the response itself instead of going
+// through get(), which exists to follow the redirect and hand back a body.
+async function latestTag(url = `https://github.com/${REPO}/releases/latest`) {
+  const { res } = await request(url, TIMEOUT_MS)
+  discard(res)
+
+  const location = redirectTo(res)
+  if (location) {
+    const tag = decodeURIComponent(location.split('/').pop() || '')
+    if (/^v?\d/.test(tag)) return tag
+    throw new Error(`could not read a release tag out of ${location}`)
+  }
+  if (res.statusCode === 403 || res.statusCode === 429) {
+    throw new Error(
+      `GitHub rate-limited the release lookup (HTTP ${res.statusCode}). Retry in a few ` +
+        'minutes, or pin the binary with AGNOSTIC_AI_VERSION=vX.Y.Z'
+    )
+  }
+  if (res.statusCode === 404) {
+    throw new Error(
+      `${REPO} reports no published release (HTTP 404). Pin one with AGNOSTIC_AI_VERSION=vX.Y.Z`
+    )
+  }
+  throw new Error(`could not resolve the latest agnostic-ai release: HTTP ${res.statusCode}`)
+}
+
 // 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
+  if (process.env.AGNOSTIC_AI_VERSION) return releaseTag(process.env.AGNOSTIC_AI_VERSION)
 
   const { version } = require('../package.json')
-  if (version && !version.startsWith('0.0.0')) return `v${version}`
+  if (version && !version.startsWith('0.0.0')) return releaseTag(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
+  return latestTag()
 }
 
 function downloadUrl(version, asset) {
@@ -90,6 +211,21 @@ async function verifyChecksum(archive, asset, version) {
   if (actual !== expected) throw new Error(`checksum mismatch for ${asset}`)
 }
 
+function extract(archive, dir) {
+  // 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.
+  try {
+    execFileSync('tar', ['-xf', archive, '-C', dir, BINARY], { stdio: 'ignore' })
+  } catch (err) {
+    const reason = err.code === 'ENOENT' ? 'tar is not installed' : describeError(err).message
+    throw new Error(
+      `could not extract ${path.basename(archive)}: ${reason}. Install agnostic-ai another ` +
+        'way instead: go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@latest, ' +
+        'or the routes at https://agnostic-ai.org/docs/installation/'
+    )
+  }
+}
+
 async function ensureBinary({ log = () => {} } = {}) {
   const dest = binaryPath()
   if (fs.existsSync(dest)) return dest
@@ -103,10 +239,7 @@ async function ensureBinary({ log = () => {} } = {}) {
     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' })
+    extract(archive, work)
 
     fs.mkdirSync(path.dirname(dest), { recursive: true })
     fs.copyFileSync(path.join(work, BINARY), dest)
@@ -119,4 +252,15 @@ async function ensureBinary({ log = () => {} } = {}) {
   return dest
 }
 
-module.exports = { assetName, binaryPath, downloadUrl, ensureBinary, resolveVersion, target }
+module.exports = {
+  assetName,
+  binaryPath,
+  describeError,
+  downloadUrl,
+  ensureBinary,
+  extract,
+  get,
+  latestTag,
+  resolveVersion,
+  target,
+}

package/lib/download_test.js

@@ -2,12 +2,98 @@
 
 // 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.
+// Covers the pure mapping logic plus the failure paths of the download: every
+// server here is a throwaway listener on 127.0.0.1, so the suite needs no
+// network and no dependencies. The happy path is exercised end to end by
+// .github/workflows/install.yml against a real release.
 
 const assert = require('node:assert')
+const { spawnSync } = require('node:child_process')
+const fs = require('node:fs')
+const http = require('node:http')
+const https = require('node:https')
+const net = require('node:net')
+const os = require('node:os')
 const path = require('node:path')
-const { assetName, binaryPath, downloadUrl, resolveVersion, target } = require('./download')
+const {
+  assetName,
+  binaryPath,
+  describeError,
+  downloadUrl,
+  extract,
+  get,
+  latestTag,
+  resolveVersion,
+  target,
+} = require('./download')
+
+function listen(server) {
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => resolve(`http://127.0.0.1:${server.address().port}`))
+  })
+}
+
+function close(server, sockets = []) {
+  return new Promise((resolve) => {
+    // close() alone waits for every open connection: the keep-alive sockets an
+    // http.Server holds, and the one the wedged server keeps open on purpose.
+    // Drop both, or the suite hangs here.
+    if (server.closeAllConnections) server.closeAllConnections()
+    for (const socket of sockets) socket.destroy()
+    server.close(resolve)
+  })
+}
+
+async function rejection(promise) {
+  try {
+    await promise
+  } catch (err) {
+    return err
+  }
+  throw new Error('expected the promise to reject')
+}
+
+function thrown(fn) {
+  try {
+    fn()
+  } catch (err) {
+    return err
+  }
+  throw new Error('expected the call to throw')
+}
+
+// A real AggregateError, thrown by Node itself: the custom lookup hands the
+// connect both loopback addresses so every attempt fails, which is the shape of
+// github.com resolving to several IPs behind a firewall. Both refuse instantly,
+// so this stays fast and needs no network.
+function multiAddressFailure(port) {
+  return new Promise((resolve) => {
+    https
+      .get(
+        `https://localhost:${port}/x`,
+        {
+          autoSelectFamily: true,
+          lookup: (host, opts, cb) =>
+            cb(null, [
+              { address: '127.0.0.1', family: 4 },
+              { address: '::1', family: 6 },
+            ]),
+        },
+        () => {}
+      )
+      .on('error', resolve)
+  })
+}
+
+function closedPort() {
+  return new Promise((resolve) => {
+    const probe = net.createServer()
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address()
+      probe.close(() => resolve(port))
+    })
+  })
+}
 
 const tests = {
   'asset name matches the release archive for this platform'() {
@@ -42,6 +128,180 @@ const tests = {
       delete process.env.AGNOSTIC_AI_VERSION
     }
   },
+
+  async 'a version pin resolves the same with or without the v prefix'() {
+    try {
+      for (const pin of ['0.61.0', 'v0.61.0', ' 0.61.0 ']) {
+        process.env.AGNOSTIC_AI_VERSION = pin
+        assert.strictEqual(await resolveVersion(), 'v0.61.0', `pin ${JSON.stringify(pin)}`)
+      }
+    } finally {
+      delete process.env.AGNOSTIC_AI_VERSION
+    }
+  },
+
+  async 'an error with no message is described from its code and its causes'() {
+    const port = await closedPort()
+    const err = await multiAddressFailure(port)
+
+    // Guard the premise: this is what the user currently sees printed.
+    assert.ok(err instanceof AggregateError, `expected an AggregateError, got ${err.name}`)
+    assert.strictEqual(err.message, '')
+
+    const described = describeError(err).message
+    assert.ok(described.length > 0, 'described message is empty')
+    assert.match(described, /ECONNREFUSED/)
+    assert.ok(described.includes(`127.0.0.1:${port}`), `missing the address: ${described}`)
+    assert.ok(described.includes('::1'), `missing the second address: ${described}`)
+  },
+
+  'an error that already has a message is left alone'() {
+    const err = new Error('connect ETIMEDOUT 203.0.113.1:443')
+    assert.strictEqual(describeError(err), err)
+  },
+
+  async 'a server that never answers fails with a timeout naming the url'() {
+    // Accept the connection and say nothing: no OS-level timeout ever fires.
+    const accepted = []
+    const server = net.createServer((socket) => accepted.push(socket))
+    const base = await listen(server)
+    try {
+      const err = await rejection(get(`${base}/wedged`, { timeoutMs: 200 }))
+      assert.ok(err.message.includes(`${base}/wedged`), `missing the url: ${err.message}`)
+      assert.match(err.message, /timed out after 0\.2s/)
+    } finally {
+      await close(server, accepted)
+    }
+  },
+
+  async 'a body that stops mid-stream reports the timeout, not `aborted`'() {
+    const server = http.createServer((req, res) => {
+      res.writeHead(200, { 'content-length': '100' })
+      res.write('half a bod') // and then nothing, ever
+    })
+    const base = await listen(server)
+    try {
+      const err = await rejection(get(`${base}/stalled`, { timeoutMs: 200 }))
+      assert.ok(err.message.includes(`${base}/stalled`), `missing the url: ${err.message}`)
+      assert.match(err.message, /timed out after 0\.2s/)
+    } finally {
+      await close(server)
+    }
+  },
+
+  async 'a single redirect is still followed'() {
+    const server = http.createServer((req, res) => {
+      if (req.url === '/asset') {
+        res.writeHead(302, { location: `${base}/storage` })
+        res.end()
+        return
+      }
+      res.writeHead(200)
+      res.end('payload')
+    })
+    const base = await listen(server)
+    try {
+      assert.strictEqual((await get(`${base}/asset`)).toString('utf8'), 'payload')
+    } finally {
+      await close(server)
+    }
+  },
+
+  async 'a redirect loop stops at the cap'() {
+    let hops = 0
+    const server = http.createServer((req, res) => {
+      hops++
+      res.writeHead(302, { location: `${base}/loop` })
+      res.end()
+    })
+    const base = await listen(server)
+    try {
+      const err = await rejection(get(`${base}/loop`))
+      assert.match(err.message, /redirect/i)
+      assert.match(err.message, /5/)
+      assert.ok(hops <= 6, `followed ${hops} hops, expected at most 6`)
+    } finally {
+      await close(server)
+    }
+  },
+
+  async 'the latest release comes from the redirect, not the rate-limited api'() {
+    const seen = []
+    const server = http.createServer((req, res) => {
+      seen.push(req.url)
+      res.writeHead(302, { location: 'https://github.com/Chemaclass/agnostic-ai/releases/tag/v0.62.0' })
+      res.end()
+    })
+    const base = await listen(server)
+    try {
+      assert.strictEqual(await latestTag(`${base}/releases/latest`), 'v0.62.0')
+      assert.deepStrictEqual(seen, ['/releases/latest'])
+    } finally {
+      await close(server)
+    }
+  },
+
+  async 'a rate-limited release lookup says so, a missing release says that'() {
+    let status = 403
+    const server = http.createServer((req, res) => {
+      res.writeHead(status)
+      res.end()
+    })
+    const base = await listen(server)
+    try {
+      const limited = await rejection(latestTag(`${base}/releases/latest`))
+      assert.match(limited.message, /rate-limited/)
+      assert.match(limited.message, /AGNOSTIC_AI_VERSION/)
+
+      status = 404
+      const missing = await rejection(latestTag(`${base}/releases/latest`))
+      assert.match(missing.message, /no published release/)
+      assert.ok(!/rate-limited/.test(missing.message), missing.message)
+    } finally {
+      await close(server)
+    }
+  },
+
+  'a failed extraction names the archive and an alternative install route'() {
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), 'agnostic-ai-extract-'))
+    try {
+      const archive = path.join(work, 'agnostic-ai_broken.tar.gz')
+      fs.writeFileSync(archive, 'not an archive')
+      const err = thrown(() => extract(archive, work))
+      assert.ok(err.message.includes('agnostic-ai_broken.tar.gz'), `missing the archive: ${err.message}`)
+      assert.match(err.message, /go install github\.com\/chemaclass\/agnostic-ai/)
+    } finally {
+      fs.rmSync(work, { recursive: true, force: true })
+    }
+  },
+
+  'the bin shim exits with 128 plus the signal number'() {
+    if (process.platform === 'win32') {
+      console.log('     skipped: no POSIX signals on windows')
+      return
+    }
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), 'agnostic-ai-shim-'))
+    try {
+      fs.mkdirSync(path.join(work, 'bin'))
+      fs.mkdirSync(path.join(work, 'lib'))
+      fs.writeFileSync(path.join(work, 'package.json'), '{"version":"0.0.0-dev"}')
+      fs.copyFileSync(path.join(__dirname, 'download.js'), path.join(work, 'lib', 'download.js'))
+      const shim = path.join(work, 'bin', 'agnostic-ai.js')
+      fs.copyFileSync(path.join(__dirname, '..', 'bin', 'agnostic-ai.js'), shim)
+
+      // ensureBinary short-circuits on an existing binary, so the shim spawns
+      // this stub instead of downloading anything. It kills itself with
+      // SIGTERM (15), so the shim must report 143.
+      const stub = path.join(work, 'bin', 'agnostic-ai')
+      fs.writeFileSync(stub, '#!/bin/sh\nkill -TERM $$\n')
+      fs.chmodSync(stub, 0o755)
+
+      const run = spawnSync(process.execPath, [shim], { encoding: 'utf8' })
+      assert.strictEqual(run.status, 128 + os.constants.signals.SIGTERM, run.stderr)
+    } finally {
+      fs.rmSync(work, { recursive: true, force: true })
+    }
+  },
 }
 
 async function run() {
@@ -56,7 +316,10 @@ async function run() {
     }
   }
   console.log(`\n${Object.keys(tests).length - failed} passed, ${failed} failed`)
-  process.exit(failed === 0 ? 0 : 1)
+  // exitCode, not exit(): process.exit() drops whatever stdout has not flushed
+  // yet, which silently swallows the tail of the report when it runs in CI with
+  // stdout on a pipe.
+  process.exitCode = failed === 0 ? 0 : 1
 }
 
 run()

package/package.json

@@ -1,19 +1,30 @@
 {
   "name": "agnostic-ai",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "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"
   },