agentworth 0.1.1 → 0.1.5

package/README.md

@@ -89,16 +89,12 @@ The launcher searches for the native binary in the following priority order:
 
 You can also install the native AgentWorth binary directly:
 
-```bash
-# Via Standalone Installer
-curl -fsSL https://agentworth.dev/install.sh | sh
-
-# Via Homebrew
-brew install unfoundbox/tap/agentworth
-
-# Via Cargo
-cargo install agentworth-cli
-```
+| Method | Command | Description |
+| :--- | :--- | :--- |
+| **Standalone Script** | `curl -fsSL https://agentworth.dev/install.sh | sh` | Installs the pre-built native binary directly to `~/.local/bin`. |
+| **Homebrew** | `brew install unfoundbox-crew/tap/agentworth` | Installs via official Homebrew tap. |
+| **Cargo (Native)** | `cargo install agentworth-cli` | Compiles and installs `agentworth` & `agwt` to `~/.cargo/bin`. |
+| **NPX (Instant)** | `npx agentworth` | Zero-install runner that detects or downloads the native binary. |
 
 ---
 

package/lib/resolver.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { spawnSync } from 'node:child_process';
+import https from 'node:https';
+import zlib from 'node:zlib';
+import { spawnSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -18,6 +20,54 @@ export function getPlatformKey(platform = process.platform, arch = process.arch)
   return `${platform}-${arch}`;
 }
 
+/**
+ * Maps Node platform and arch to Rust release target triple.
+ *
+ * @param {string} [platform=process.platform]
+ * @param {string} [arch=process.arch]
+ * @returns {string | null}
+ */
+export function getTargetTriple(platform = process.platform, arch = process.arch) {
+  if (platform === 'darwin' && arch === 'arm64') return 'aarch64-apple-darwin';
+  if (platform === 'darwin' && arch === 'x64') return 'x86_64-apple-darwin';
+  if (platform === 'linux' && arch === 'x64') return 'x86_64-unknown-linux-gnu';
+  if (platform === 'linux' && arch === 'arm64') return 'aarch64-unknown-linux-gnu';
+  if (platform === 'win32' && arch === 'x64') return 'x86_64-pc-windows-msvc';
+  return null;
+}
+
+/**
+ * Reads the package version from package.json.
+ *
+ * @param {string} [baseDir=__dirname]
+ * @returns {string}
+ */
+export function getPackageVersion(baseDir = __dirname) {
+  try {
+    const pkgPath = path.resolve(baseDir, '..', 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const data = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      return data.version || '0.1.3';
+    }
+  } catch {
+    // fallback
+  }
+  return '0.1.3';
+}
+
+/**
+ * Returns the local cache directory for AgentWorth binaries (~/.agentworth/bin/v{version}/).
+ *
+ * @param {string} [version]
+ * @param {string} [homeDir]
+ * @returns {string}
+ */
+export function getCacheDir(version, homeDir) {
+  const v = version || getPackageVersion();
+  const home = homeDir || os.homedir();
+  return path.join(home, '.agentworth', 'bin', `v${v}`);
+}
+
 /**
  * Returns the expected native binary name for the target platform.
  *
@@ -95,6 +145,117 @@ export function findCargoTargetBinary(startDir, binName = getBinaryName()) {
   return null;
 }
 
+/**
+ * Downloads a file following HTTP redirects.
+ *
+ * @param {string} url
+ * @param {string} destPath
+ * @param {number} [redirects=5]
+ * @returns {Promise<void>}
+ */
+export function downloadFile(url, destPath, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (redirects < 0) {
+      return reject(new Error('Too many redirects while downloading binary.'));
+    }
+
+    const request = https.get(url, { headers: { 'User-Agent': 'agentworth-npm-resolver' } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return downloadFile(res.headers.location, destPath, redirects - 1).then(resolve, reject);
+      }
+
+      if (res.statusCode !== 200) {
+        return reject(new Error(`Failed to download binary: HTTP ${res.statusCode} from ${url}`));
+      }
+
+      const fileStream = fs.createWriteStream(destPath);
+      res.pipe(fileStream);
+
+      fileStream.on('finish', () => {
+        fileStream.close(resolve);
+      });
+
+      fileStream.on('error', (err) => {
+        fs.unlink(destPath, () => reject(err));
+      });
+    });
+
+    request.on('error', (err) => {
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Downloads and extracts the precompiled native binary from GitHub Releases into the user's local cache.
+ *
+ * @param {Object} [options={}]
+ * @param {string} [options.platform=process.platform]
+ * @param {string} [options.arch=process.arch]
+ * @param {string} [options.version]
+ * @param {string} [options.homeDir]
+ * @param {boolean} [options.silent=false]
+ * @returns {Promise<string>} Path to extracted binary
+ */
+export async function downloadAndExtractBinary(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const version = options.version || getPackageVersion();
+  const targetTriple = getTargetTriple(platform, arch);
+  const binName = getBinaryName(platform);
+
+  if (!targetTriple) {
+    throw new Error(`Unsupported platform/architecture: ${platform}-${arch}`);
+  }
+
+  const cacheDir = getCacheDir(version, options.homeDir);
+  const cachedBinary = path.join(cacheDir, binName);
+
+  if (isExecutable(cachedBinary)) {
+    return cachedBinary;
+  }
+
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const archiveName = `agentworth-v${version}-${targetTriple}.tar.gz`;
+  const url = `https://github.com/unfoundbox-crew/agentworth/releases/download/v${version}/${archiveName}`;
+
+  if (!options.silent) {
+    console.error(`\x1b[36m⚡ AgentWorth native binary not found locally. Downloading v${version} for ${platform}-${arch}...\x1b[0m`);
+  }
+
+  const archivePath = path.join(cacheDir, archiveName);
+
+  await downloadFile(url, archivePath);
+
+  // Extract archive
+  try {
+    execFileSync('tar', ['-xzf', archivePath, '-C', cacheDir]);
+  } catch (err) {
+    throw new Error(`Failed to extract ${archiveName}: ${err.message}`);
+  } finally {
+    try {
+      if (fs.existsSync(archivePath)) {
+        fs.unlinkSync(archivePath);
+      }
+    } catch {}
+  }
+
+  if (process.platform !== 'win32') {
+    fs.chmodSync(cachedBinary, 0o755);
+  }
+
+  if (!isExecutable(cachedBinary)) {
+    throw new Error(`Downloaded binary is not executable: ${cachedBinary}`);
+  }
+
+  if (!options.silent) {
+    console.error(`\x1b[32m✔ Successfully installed AgentWorth native binary to ${cachedBinary}\x1b[0m\n`);
+  }
+
+  return cachedBinary;
+}
+
 /**
  * Searches for the agentworth binary in the system PATH.
  *
@@ -103,6 +264,36 @@ export function findCargoTargetBinary(startDir, binName = getBinaryName()) {
  * @param {string} [currentScriptPath]
  * @returns {string | null}
  */
+/**
+ * True when `candidate` and `selfPath` are the same file, following symlinks.
+ */
+export function isSelf(candidate, selfPath) {
+  if (!selfPath) return false;
+  try {
+    return fs.realpathSync(candidate) === fs.realpathSync(selfPath);
+  } catch {
+    return path.resolve(candidate) === path.resolve(selfPath);
+  }
+}
+
+/**
+ * True when `candidate` is a Node script (a bin shim) rather than the native
+ * binary. Covers shims that are copies rather than symlinks.
+ */
+export function looksLikeNodeScript(filePath) {
+  try {
+    if (/\.(js|cjs|mjs)$/.test(filePath)) return true;
+    const fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(64);
+    const n = fs.readSync(fd, buf, 0, 64, 0);
+    fs.closeSync(fd);
+    const first = buf.subarray(0, n).toString('utf8').split('\n')[0];
+    return first.startsWith('#!') && /\bnode\b/.test(first);
+  } catch {
+    return false;
+  }
+}
+
 export function findPathBinary(binName = getBinaryName(), pathEnv = process.env.PATH, currentScriptPath) {
   if (!pathEnv) {
     return null;
@@ -113,8 +304,12 @@ export function findPathBinary(binName = getBinaryName(), pathEnv = process.env.
     if (!entry) continue;
     const candidate = path.join(entry, binName);
     if (isExecutable(candidate)) {
-      // Avoid circular invocation if PATH points to this JS wrapper script
-      if (currentScriptPath && path.resolve(candidate) === path.resolve(currentScriptPath)) {
+      // Avoid circular invocation if PATH points back at this JS wrapper.
+      // npm/npx put node_modules/.bin on PATH and the entry there is a SYMLINK
+      // to this very file. path.resolve() does not follow symlinks, so this guard
+      // missed it and the launcher spawned itself until the OS refused to fork
+      // (EAGAIN on macOS, v0.1.4). Compare real paths, and reject Node scripts.
+      if (isSelf(candidate, currentScriptPath) || looksLikeNodeScript(candidate)) {
         continue;
       }
       return candidate;
@@ -130,11 +325,12 @@ export function findPathBinary(binName = getBinaryName(), pathEnv = process.env.
  * Search priority:
  * 1. AGENTWORTH_BIN environment variable
  * 2. Platform-specific optional package / vendor directory
- * 3. Cargo target in cwd directory hierarchy (release or debug)
- * 4. Cargo target in package directory hierarchy
- * 5. CARGO_TARGET_DIR if set
- * 6. User ~/.cargo/bin/
- * 7. System PATH
+ * 3. System PATH
+ * 4. Cargo target in cwd directory hierarchy (release or debug)
+ * 5. Cargo target in package directory hierarchy
+ * 6. CARGO_TARGET_DIR if set
+ * 7. User ~/.cargo/bin/
+ * 8. User local cache ~/.agentworth/bin/v{version}/
  *
  * @param {Object} [options={}]
  * @param {string} [options.cwd=process.cwd()]
@@ -142,6 +338,7 @@ export function findPathBinary(binName = getBinaryName(), pathEnv = process.env.
  * @param {string} [options.arch=process.arch]
  * @param {NodeJS.ProcessEnv} [options.env=process.env]
  * @param {string} [options.baseDir=__dirname]
+ * @param {string} [options.homeDir]
  * @returns {{ found: boolean, path?: string, source?: string, error?: string }}
  */
 export function resolveBinary(options = {}) {
@@ -150,6 +347,7 @@ export function resolveBinary(options = {}) {
   const arch = options.arch || process.arch;
   const env = options.env || process.env;
   const baseDir = options.baseDir || __dirname;
+  const homeDir = options.homeDir || (env.HOME ? env.HOME : os.homedir());
   const binName = getBinaryName(platform);
   const platformKey = getPlatformKey(platform, arch);
 
@@ -172,7 +370,21 @@ export function resolveBinary(options = {}) {
     };
   }
 
-  // 3. Local Cargo target from working directory
+  // 3. System PATH (highest user priority for installed binaries)
+  // Skipped when already inside a launcher: the only thing PATH could offer is us.
+  const currentBin = path.resolve(baseDir, '..', 'bin', 'agentworth.js');
+  if (env.PATH !== undefined && !env.AGENTWORTH_LAUNCHER_ACTIVE) {
+    const pathBin = findPathBinary(binName, env.PATH, currentBin);
+    if (pathBin) {
+      return {
+        found: true,
+        path: pathBin,
+        source: 'path',
+      };
+    }
+  }
+
+  // 4. Local Cargo target from working directory
   const cwdCargoBin = findCargoTargetBinary(cwd, binName);
   if (cwdCargoBin) {
     return {
@@ -182,7 +394,7 @@ export function resolveBinary(options = {}) {
     };
   }
 
-  // 4. Local Cargo target from package directory hierarchy
+  // 5. Local Cargo target from package directory hierarchy
   const pkgCargoBin = findCargoTargetBinary(baseDir, binName);
   if (pkgCargoBin) {
     return {
@@ -192,7 +404,7 @@ export function resolveBinary(options = {}) {
     };
   }
 
-  // 5. CARGO_TARGET_DIR environment variable if specified
+  // 6. CARGO_TARGET_DIR environment variable if specified
   if (env.CARGO_TARGET_DIR) {
     const targetDirRelease = path.join(env.CARGO_TARGET_DIR, 'release', binName);
     if (isExecutable(targetDirRelease)) {
@@ -212,25 +424,27 @@ export function resolveBinary(options = {}) {
     }
   }
 
-  // 6. User ~/.cargo/bin directory
-  const cargoHomeBin = path.join(os.homedir(), '.cargo', 'bin', binName);
-  if (isExecutable(cargoHomeBin)) {
-    return {
-      found: true,
-      path: cargoHomeBin,
-      source: 'cargo-home-bin',
-    };
-  }
+  // 7. User ~/.cargo/bin directory
+  if (homeDir) {
+    const cargoHomeBin = path.join(homeDir, '.cargo', 'bin', binName);
+    if (isExecutable(cargoHomeBin)) {
+      return {
+        found: true,
+        path: cargoHomeBin,
+        source: 'cargo-home-bin',
+      };
+    }
 
-  // 7. System PATH
-  const currentBin = path.resolve(baseDir, '..', 'bin', 'agentworth.js');
-  const pathBin = findPathBinary(binName, env.PATH, currentBin);
-  if (pathBin) {
-    return {
-      found: true,
-      path: pathBin,
-      source: 'path',
-    };
+    // 8. User local cache (~/.agentworth/bin/v{version}/)
+    const cacheDir = getCacheDir(getPackageVersion(baseDir), homeDir);
+    const cachedBin = path.join(cacheDir, binName);
+    if (isExecutable(cachedBin)) {
+      return {
+        found: true,
+        path: cachedBin,
+        source: 'cache',
+      };
+    }
   }
 
   return {
@@ -257,11 +471,8 @@ export function formatMissingBinaryMessage(platformKey = getPlatformKey()) {
     '  \x1b[36m• Install via Cargo:\x1b[0m',
     '      cargo install --path apps/cli',
     '',
-    '  \x1b[36m• Install via Homebrew:\x1b[0m',
-    '      brew install agentworth',
-    '',
-    '  \x1b[36m• Install via Shell script:\x1b[0m',
-    '      curl -fsSL https://agentworth.dev/install.sh | sh',
+    '  \x1b[36m• Download the release for your platform:\x1b[0m',
+    `      https://github.com/unfoundbox-crew/agentworth/releases/latest`,
     '',
     '  \x1b[36m• Set custom binary path:\x1b[0m',
     '      export AGENTWORTH_BIN=/path/to/agentworth',
@@ -278,7 +489,32 @@ export function formatMissingBinaryMessage(platformKey = getPlatformKey()) {
  */
 export function run(argv = process.argv.slice(2), options = {}) {
   const resolvedArgs = resolveArguments(argv);
-  const binaryResult = resolveBinary(options);
+  let binaryResult = resolveBinary(options);
+
+  // If binary not found on clean machine, attempt on-demand download from GitHub Release
+  if ((!binaryResult.found || !binaryResult.path) && options.autoDownload !== false) {
+    try {
+      const resolverModuleUrl = new URL('./resolver.js', import.meta.url).href;
+      const syncDownloadScript = `
+        import { downloadAndExtractBinary } from '${resolverModuleUrl}';
+        await downloadAndExtractBinary({
+          platform: ${JSON.stringify(options.platform || process.platform)},
+          arch: ${JSON.stringify(options.arch || process.arch)},
+          homeDir: ${JSON.stringify(options.homeDir || (options.env && options.env.HOME) || '')}
+        });
+      `;
+      const dlResult = spawnSync(process.execPath, ['--input-type=module', '-e', syncDownloadScript], {
+        stdio: 'inherit',
+        env: options.env || process.env,
+      });
+
+      if (dlResult.status === 0) {
+        binaryResult = resolveBinary(options);
+      }
+    } catch {
+      // Fall through to error message below
+    }
+  }
 
   if (!binaryResult.found || !binaryResult.path) {
     const message = formatMissingBinaryMessage(getPlatformKey(options.platform, options.arch));
@@ -286,9 +522,11 @@ export function run(argv = process.argv.slice(2), options = {}) {
     return 1;
   }
 
+  // Belt and braces: a child that somehow re-enters this launcher cannot loop.
+  const childEnv = { ...(options.env || process.env), AGENTWORTH_LAUNCHER_ACTIVE: '1' };
   const result = spawnSync(binaryResult.path, resolvedArgs, {
     stdio: 'inherit',
-    env: options.env || process.env,
+    env: childEnv,
   });
 
   if (result.error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentworth",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "description": "Discover, normalize, and understand AI-agent histories locally.",
   "type": "module",
   "main": "./lib/resolver.js",
@@ -23,8 +23,16 @@
     "analytics",
     "developer-tools"
   ],
-  "author": "Unfoundbox",
+  "author": "Unfoundbox Crew",
   "license": "Apache-2.0",
+  "homepage": "https://agentworth.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unfoundbox-crew/agentworth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unfoundbox-crew/agentworth/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },