@hyperengineering/recall 1.2.0

package/README.md

@@ -0,0 +1,178 @@
+# @hyperengineering/recall
+
+CLI for managing experiential lore from AI agent workflows.
+
+This npm package provides a convenient way to install and use the `recall` CLI tool. The package automatically downloads the correct binary for your platform during installation.
+
+## Installation
+
+```bash
+npm install @hyperengineering/recall
+```
+
+Or with yarn:
+
+```bash
+yarn add @hyperengineering/recall
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @hyperengineering/recall
+```
+
+## Usage
+
+After installation, the `recall` command is available:
+
+```bash
+npx recall --help
+```
+
+Or if installed globally:
+
+```bash
+npm install -g @hyperengineering/recall
+recall --help
+```
+
+## Supported Platforms
+
+| OS | Architecture | Supported |
+|----|--------------|-----------|
+| macOS | x64 (Intel) | Yes |
+| macOS | arm64 (Apple Silicon) | Yes |
+| Linux | x64 | Yes |
+| Linux | arm64 | Yes |
+| Windows | x64 | Yes |
+| Windows | arm64 | No |
+
+## Environment Variables
+
+### `RECALL_SKIP_DOWNLOAD`
+
+Set to `1` to skip the binary download during installation. Useful when:
+- You want to install the binary manually
+- You're caching the binary in CI/CD
+- The download is blocked by network restrictions
+
+```bash
+RECALL_SKIP_DOWNLOAD=1 npm install @hyperengineering/recall
+```
+
+### `RECALL_BINARY_PATH`
+
+Point to a custom binary location instead of the downloaded one:
+
+```bash
+export RECALL_BINARY_PATH=/usr/local/bin/recall
+npx recall --help
+```
+
+## CI/CD Usage
+
+### GitHub Actions
+
+```yaml
+- name: Install recall
+  run: npm install @hyperengineering/recall
+
+- name: Use recall
+  run: npx recall version
+```
+
+With caching:
+
+```yaml
+- name: Cache recall binary
+  uses: actions/cache@v4
+  with:
+    path: node_modules/@hyperengineering/recall/vendor
+    key: recall-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package-lock.json') }}
+
+- name: Install recall
+  run: npm install @hyperengineering/recall
+```
+
+### GitLab CI
+
+```yaml
+install:
+  script:
+    - npm install @hyperengineering/recall
+    - npx recall version
+  cache:
+    paths:
+      - node_modules/
+```
+
+### Skip Download (Pre-installed Binary)
+
+If you have recall installed via Homebrew or another method:
+
+```yaml
+- name: Install recall via Homebrew
+  run: brew install hyperengineering/tap/recall
+
+- name: Install npm package (skip download)
+  run: RECALL_SKIP_DOWNLOAD=1 npm install @hyperengineering/recall
+  env:
+    RECALL_BINARY_PATH: /usr/local/bin/recall
+```
+
+## Troubleshooting
+
+### Binary not found after installation
+
+The binary may have failed to download. Try:
+
+1. Run `npm rebuild @hyperengineering/recall` to re-download
+2. Check for network issues (firewalls, proxies)
+3. Install manually using one of the alternatives below
+
+### Download fails in restricted environments
+
+Some environments block downloads during npm install. Solutions:
+
+1. Pre-download the binary and use `RECALL_BINARY_PATH`
+2. Use the Homebrew tap: `brew install hyperengineering/tap/recall`
+3. Download from [GitHub Releases](https://github.com/hyperengineering/recall/releases)
+
+### Permission denied on Unix
+
+The binary should have executable permissions set automatically. If not:
+
+```bash
+chmod +x node_modules/@hyperengineering/recall/vendor/recall
+```
+
+## Alternative Installation Methods
+
+If npm installation doesn't work for your use case:
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew install hyperengineering/tap/recall
+```
+
+### Direct Download
+
+Download the binary for your platform from [GitHub Releases](https://github.com/hyperengineering/recall/releases).
+
+### Go Install
+
+```bash
+go install github.com/hyperengineering/recall/cmd/recall@latest
+```
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub Repository](https://github.com/hyperengineering/recall)
+- [Documentation](https://github.com/hyperengineering/recall#readme)
+- [Issues](https://github.com/hyperengineering/recall/issues)

package/bin/recall.cmd

@@ -0,0 +1,6 @@
+@echo off
+
+:: Wrapper script for recall binary on Windows
+:: This is a compatibility shim for npm on Windows
+
+node "%~dp0recall.js" %*

package/bin/recall.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+/**
+ * Wrapper script for recall binary.
+ * Executes the downloaded binary with all arguments.
+ */
+
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const SCRIPT_DIR = __dirname;
+const VENDOR_DIR = path.join(SCRIPT_DIR, '..', 'vendor');
+
+function getBinaryPath() {
+  // Check for custom binary path
+  if (process.env.RECALL_BINARY_PATH) {
+    return process.env.RECALL_BINARY_PATH;
+  }
+
+  // Determine binary name based on platform
+  const binaryName = process.platform === 'win32' ? 'recall.exe' : 'recall';
+  const binaryPath = path.join(VENDOR_DIR, binaryName);
+
+  return binaryPath;
+}
+
+function main() {
+  const binaryPath = getBinaryPath();
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error(`Error: recall binary not found at ${binaryPath}`);
+    console.error('');
+    console.error('Run one of the following to download the binary:');
+    console.error('  npm rebuild @hyperengineering/recall');
+    console.error('');
+    console.error('Or set RECALL_BINARY_PATH to point to your recall installation');
+    process.exit(1);
+  }
+
+  // Pass through all arguments to the binary
+  const args = process.argv.slice(2);
+
+  const child = spawn(binaryPath, args, {
+    stdio: 'inherit',
+    windowsHide: true
+  });
+
+  child.on('error', (err) => {
+    console.error(`Error executing recall: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.exit(1);
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+main();

package/lib/download.js

@@ -0,0 +1,123 @@
+/**
+ * Binary download with retry logic.
+ */
+
+'use strict';
+
+const https = require('https');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000;
+
+/**
+ * Download a file from URL to destination path.
+ * @param {string} url - Download URL
+ * @param {string} destPath - Destination file path
+ * @param {object} options - Options
+ * @param {number} [options.retries=3] - Number of retries
+ * @param {function} [options.onProgress] - Progress callback (received, total)
+ * @returns {Promise<void>}
+ */
+async function download(url, destPath, options = {}) {
+  const { retries = MAX_RETRIES, onProgress } = options;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      await downloadOnce(url, destPath, onProgress);
+      return;
+    } catch (err) {
+      if (attempt === retries) {
+        throw err;
+      }
+      const delay = RETRY_DELAY_MS * Math.pow(2, attempt - 1);
+      console.log(`Download failed (attempt ${attempt}/${retries}), retrying in ${delay}ms...`);
+      await sleep(delay);
+    }
+  }
+}
+
+/**
+ * Download a file once (no retries).
+ * @param {string} url - Download URL
+ * @param {string} destPath - Destination file path
+ * @param {function} [onProgress] - Progress callback
+ * @returns {Promise<void>}
+ */
+function downloadOnce(url, destPath, onProgress) {
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith('https') ? https : http;
+
+    const request = protocol.get(url, {
+      headers: { 'User-Agent': 'npm-@hyperengineering/recall' }
+    }, (response) => {
+      // Handle redirects
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        downloadOnce(response.headers.location, destPath, onProgress)
+          .then(resolve)
+          .catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`Download failed: HTTP ${response.statusCode}`));
+        return;
+      }
+
+      const totalBytes = parseInt(response.headers['content-length'], 10) || 0;
+      let receivedBytes = 0;
+
+      const dir = path.dirname(destPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      const fileStream = fs.createWriteStream(destPath);
+
+      response.on('data', (chunk) => {
+        receivedBytes += chunk.length;
+        if (onProgress && totalBytes > 0) {
+          onProgress(receivedBytes, totalBytes);
+        }
+      });
+
+      response.pipe(fileStream);
+
+      fileStream.on('finish', () => {
+        fileStream.close();
+        resolve();
+      });
+
+      fileStream.on('error', (err) => {
+        fs.unlink(destPath, () => {}); // Clean up partial file
+        reject(err);
+      });
+    });
+
+    request.on('error', (err) => {
+      // Clean up partial file if it exists
+      if (fs.existsSync(destPath)) {
+        fs.unlinkSync(destPath);
+      }
+      reject(err);
+    });
+
+    request.on('timeout', () => {
+      request.destroy();
+      reject(new Error('Download timed out'));
+    });
+  });
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+module.exports = { download };

package/lib/extract.js

@@ -0,0 +1,77 @@
+/**
+ * Archive extraction for tar.gz and zip files.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract archive to destination directory.
+ * @param {string} archivePath - Path to archive file
+ * @param {string} destDir - Destination directory
+ * @param {{ ext: string, os?: string }} platform - Platform info with extension
+ * @returns {Promise<void>}
+ */
+async function extract(archivePath, destDir, platform) {
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  if (platform.ext === 'zip') {
+    await extractZip(archivePath, destDir);
+  } else {
+    await extractTarGz(archivePath, destDir);
+  }
+}
+
+/**
+ * Extract tar.gz archive, filtering for recall binary only.
+ * @param {string} archivePath - Path to tar.gz file
+ * @param {string} destDir - Destination directory
+ * @returns {Promise<void>}
+ */
+async function extractTarGz(archivePath, destDir) {
+  const tar = require('tar');
+
+  await tar.extract({
+    file: archivePath,
+    cwd: destDir,
+    filter: (entryPath) => {
+      // Only extract the recall binary, skip README etc.
+      const basename = path.basename(entryPath);
+      return basename === 'recall' || basename === 'recall.exe';
+    }
+  });
+}
+
+/**
+ * Extract zip archive, filtering for recall binary only.
+ * @param {string} archivePath - Path to zip file
+ * @param {string} destDir - Destination directory
+ * @returns {Promise<void>}
+ */
+async function extractZip(archivePath, destDir) {
+  const AdmZip = require('adm-zip');
+  const zip = new AdmZip(archivePath);
+
+  zip.getEntries().forEach((entry) => {
+    const basename = path.basename(entry.entryName);
+    if (basename === 'recall' || basename === 'recall.exe') {
+      zip.extractEntryTo(entry, destDir, false, true);
+    }
+  });
+}
+
+/**
+ * Set executable permissions on the binary (Unix only).
+ * @param {string} binaryPath - Path to binary
+ */
+function setExecutable(binaryPath) {
+  if (process.platform !== 'win32') {
+    fs.chmodSync(binaryPath, 0o755);
+  }
+}
+
+module.exports = { extract, setExecutable };

package/lib/platform.js

@@ -0,0 +1,68 @@
+/**
+ * Platform detection for binary downloads.
+ * Maps Node.js platform/arch to GoReleaser naming conventions.
+ */
+
+'use strict';
+
+const PLATFORM_MAP = {
+  darwin: 'darwin',
+  linux: 'linux',
+  win32: 'windows'
+};
+
+const ARCH_MAP = {
+  x64: 'amd64',
+  arm64: 'arm64'
+};
+
+/**
+ * Get the current platform info for binary download.
+ * @returns {{ os: string, arch: string, ext: string }}
+ */
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  const os = PLATFORM_MAP[platform];
+  if (!os) {
+    throw new Error(`Unsupported platform: ${platform}. Supported: darwin, linux, win32`);
+  }
+
+  const goArch = ARCH_MAP[arch];
+  if (!goArch) {
+    throw new Error(`Unsupported architecture: ${arch}. Supported: x64, arm64`);
+  }
+
+  // Windows arm64 is not supported by GoReleaser config
+  if (os === 'windows' && goArch === 'arm64') {
+    throw new Error('Windows ARM64 is not currently supported. Please use x64.');
+  }
+
+  const ext = os === 'windows' ? 'zip' : 'tar.gz';
+
+  return { os, arch: goArch, ext };
+}
+
+/**
+ * Construct the GitHub release download URL.
+ * @param {string} version - Package version (e.g., "1.2.3")
+ * @param {{ os: string, arch: string, ext: string }} platform
+ * @returns {string}
+ */
+function getDownloadUrl(version, platform) {
+  const { os, arch, ext } = platform;
+  const filename = `recall_${version}_${os}_${arch}.${ext}`;
+  return `https://github.com/hyperengineering/recall/releases/download/v${version}/${filename}`;
+}
+
+/**
+ * Get the binary filename for the current platform.
+ * @param {{ os: string }} platform
+ * @returns {string}
+ */
+function getBinaryName(platform) {
+  return platform.os === 'windows' ? 'recall.exe' : 'recall';
+}
+
+module.exports = { getPlatform, getDownloadUrl, getBinaryName };

package/lib/postinstall.js

@@ -0,0 +1,71 @@
+/**
+ * Postinstall helper functions.
+ * Provides testable utilities for the postinstall script.
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Check if download should be skipped via environment variable.
+ * @returns {boolean}
+ */
+function shouldSkipDownload() {
+  return process.env.RECALL_SKIP_DOWNLOAD === '1';
+}
+
+/**
+ * Get custom binary path from environment variable.
+ * @returns {string|null}
+ */
+function getCustomBinaryPath() {
+  return process.env.RECALL_BINARY_PATH || null;
+}
+
+/**
+ * Check if binary exists at the given path.
+ * @param {string} binaryPath - Path to check
+ * @returns {boolean}
+ */
+function binaryExists(binaryPath) {
+  return fs.existsSync(binaryPath);
+}
+
+/**
+ * Print manual installation instructions.
+ * @param {Error} err - The error that occurred
+ */
+function printManualInstructions(err) {
+  console.error('\n');
+  console.error('Failed to install recall binary:');
+  console.error(err.message);
+  console.error('\n');
+  console.error('Manual installation options:');
+  console.error('  1. Homebrew (macOS/Linux): brew install hyperengineering/tap/recall');
+  console.error('  2. Download from: https://github.com/hyperengineering/recall/releases');
+  console.error('  3. Go install: go install github.com/hyperengineering/recall/cmd/recall@latest');
+  console.error('\n');
+  console.error('To skip this download, set RECALL_SKIP_DOWNLOAD=1');
+  console.error('To use a custom binary, set RECALL_BINARY_PATH=/path/to/recall');
+  console.error('\n');
+}
+
+/**
+ * Format download progress as percentage.
+ * @param {number} received - Bytes received
+ * @param {number} total - Total bytes
+ * @returns {number} - Percentage (0-100)
+ */
+function formatProgress(received, total) {
+  if (total === 0) return 0;
+  return Math.round((received / total) * 100);
+}
+
+module.exports = {
+  shouldSkipDownload,
+  getCustomBinaryPath,
+  binaryExists,
+  printManualInstructions,
+  formatProgress
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hyperengineering/recall",
+  "version": "1.2.0",
+  "description": "CLI for managing experiential lore from AI agent workflows",
+  "keywords": [
+    "recall",
+    "lore",
+    "ai",
+    "mcp",
+    "cli"
+  ],
+  "homepage": "https://github.com/hyperengineering/recall",
+  "bugs": {
+    "url": "https://github.com/hyperengineering/recall/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hyperengineering/recall.git",
+    "directory": "npm"
+  },
+  "license": "MIT",
+  "author": "Hyperengineering",
+  "bin": {
+    "recall": "./bin/recall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "vendor/",
+    "README.md"
+  ],
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "tar": "^7.4.3"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for @hyperengineering/recall.
+ * Downloads and installs the recall binary for the current platform.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getPlatform, getDownloadUrl, getBinaryName } = require('../lib/platform');
+const { download } = require('../lib/download');
+const { extract, setExecutable } = require('../lib/extract');
+const {
+  shouldSkipDownload,
+  getCustomBinaryPath,
+  binaryExists,
+  printManualInstructions,
+  formatProgress
+} = require('../lib/postinstall');
+
+const packageJson = require('../package.json');
+const VERSION = packageJson.version;
+
+const VENDOR_DIR = path.join(__dirname, '..', 'vendor');
+const CACHE_DIR = path.join(__dirname, '..', '.cache');
+
+async function main() {
+  // Check for skip flag
+  if (shouldSkipDownload()) {
+    console.log('RECALL_SKIP_DOWNLOAD is set, skipping binary download.');
+    return;
+  }
+
+  // Check for custom binary path
+  const customPath = getCustomBinaryPath();
+  if (customPath) {
+    console.log(`Using custom binary path: ${customPath}`);
+    return;
+  }
+
+  try {
+    const platform = getPlatform();
+    const binaryName = getBinaryName(platform);
+    const binaryPath = path.join(VENDOR_DIR, binaryName);
+
+    // Check if binary already exists
+    if (binaryExists(binaryPath)) {
+      console.log(`recall binary already exists at ${binaryPath}`);
+      return;
+    }
+
+    console.log(`Installing recall v${VERSION} for ${platform.os}/${platform.arch}...`);
+
+    // Create directories
+    if (!fs.existsSync(VENDOR_DIR)) {
+      fs.mkdirSync(VENDOR_DIR, { recursive: true });
+    }
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+
+    // Download archive
+    const downloadUrl = getDownloadUrl(VERSION, platform);
+    const archiveName = `recall_${VERSION}_${platform.os}_${platform.arch}.${platform.ext}`;
+    const archivePath = path.join(CACHE_DIR, archiveName);
+
+    console.log(`Downloading from ${downloadUrl}...`);
+    await download(downloadUrl, archivePath, {
+      onProgress: (received, total) => {
+        const percent = formatProgress(received, total);
+        process.stdout.write(`\rDownloading: ${percent}%`);
+      }
+    });
+    console.log('\nDownload complete.');
+
+    // Extract binary
+    console.log('Extracting binary...');
+    await extract(archivePath, VENDOR_DIR, platform);
+
+    // Set executable permissions
+    setExecutable(binaryPath);
+
+    // Verify binary exists
+    if (!binaryExists(binaryPath)) {
+      throw new Error(`Binary not found after extraction: ${binaryPath}`);
+    }
+
+    // Clean up archive
+    try {
+      fs.unlinkSync(archivePath);
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    console.log(`recall v${VERSION} installed successfully!`);
+    console.log(`Binary location: ${binaryPath}`);
+
+  } catch (err) {
+    printManualInstructions(err);
+
+    // Don't fail npm install - just warn
+    process.exit(0);
+  }
+}
+
+main();