@helmoragent/helmor 0.1.3

package/README.md

@@ -0,0 +1,21 @@
+# HELMOR Agent OS
+
+Npm installer for the native `helmor` CLI.
+
+```bash
+npm i -g @helmoragent/helmor
+helmor install
+```
+
+One-off usage without a global install:
+
+```bash
+npx @helmoragent/helmor@latest install
+pnpm dlx @helmoragent/helmor install
+yarn dlx @helmoragent/helmor install
+bunx @helmoragent/helmor install
+```
+
+This package downloads the matching HELMOR release binary from GitHub, verifies it against the published SHA-256 checksum file, and exposes the `helmor` command.
+
+Set `HELMOR_VERSION`, `HELMOR_REPO`, or `HELMOR_NPM_QUIET=1` to override the release tag, source repository, or install logging.

package/bin/helmor.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+
+const packageRoot = path.resolve(__dirname, '..');
+const executable = process.platform === 'win32' ? 'helmor.exe' : 'helmor';
+const binaryPath = path.join(packageRoot, 'vendor', executable);
+
+function installIfMissing() {
+  if (fs.existsSync(binaryPath)) {
+    return;
+  }
+
+  const installer = path.join(packageRoot, 'scripts', 'install.js');
+  const result = spawnSync(process.execPath, [installer], {
+    stdio: 'inherit',
+    env: process.env
+  });
+
+  if (result.error) {
+    console.error(`helmor: failed to run installer: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+installIfMissing();
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit'
+});
+
+child.on('error', (err) => {
+  console.error(`helmor: failed to run native binary: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code == null ? 1 : code);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@helmoragent/helmor",
+  "version": "0.1.3",
+  "description": "Agent watcher for AI-assisted product development",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/helmorx/agent-os",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helmorx/agent-os.git",
+    "directory": "npm/helmor"
+  },
+  "bugs": {
+    "url": "https://github.com/helmorx/agent-os/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "codex",
+    "claude",
+    "cursor",
+    "windsurf"
+  ],
+  "bin": {
+    "helmor": "bin/helmor.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "node --test test/*.test.js",
+    "pack:dry": "npm pack --dry-run --json"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+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 { spawnSync } = require('node:child_process');
+
+const pkg = require('../package.json');
+const {
+  checksumFor,
+  platformTarget,
+  releaseBaseUrl,
+  tagFromVersion
+} = require('./lib');
+
+const packageRoot = path.resolve(__dirname, '..');
+const vendorDir = path.join(packageRoot, 'vendor');
+
+function log(message) {
+  if (!process.env.HELMOR_NPM_QUIET) {
+    console.log(message);
+  }
+}
+
+function downloadFile(url, destination, redirects = 0) {
+  if (redirects > 5) {
+    return Promise.reject(new Error(`too many redirects for ${url}`));
+  }
+
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, {
+      headers: {
+        'user-agent': `helmor-npm/${pkg.version}`
+      }
+    }, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        const redirectUrl = new URL(response.headers.location, url).toString();
+        downloadFile(redirectUrl, destination, redirects + 1).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`download failed with HTTP ${response.statusCode}: ${url}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destination, { mode: 0o600 });
+      response.pipe(file);
+
+      file.on('finish', () => {
+        file.close(resolve);
+      });
+
+      file.on('error', (err) => {
+        fs.rm(destination, { force: true }, () => reject(err));
+      });
+    });
+
+    request.on('error', reject);
+  });
+}
+
+function sha256(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    stdio: 'inherit'
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`${command} exited with status ${result.status}`);
+  }
+}
+
+function quotePowerShell(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function extractArchive(archivePath, destination, target) {
+  if (target.archiveExt === 'zip') {
+    const command = `Expand-Archive -LiteralPath ${quotePowerShell(archivePath)} -DestinationPath ${quotePowerShell(destination)} -Force`;
+    run('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', command]);
+    return;
+  }
+
+  run('tar', ['-xzf', archivePath, '-C', destination]);
+}
+
+function verifyInstalledVersion(binaryPath, expectedVersion) {
+  const result = spawnSync(binaryPath, ['version'], {
+    encoding: 'utf8'
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`helmor version exited with status ${result.status}`);
+  }
+
+  const actualVersion = result.stdout.trim();
+  if (actualVersion !== expectedVersion) {
+    throw new Error(`expected helmor ${expectedVersion}, got ${actualVersion}`);
+  }
+}
+
+async function main() {
+  const repo = process.env.HELMOR_REPO || 'helmorx/agent-os';
+  const tag = tagFromVersion(process.env.HELMOR_VERSION || pkg.version);
+  const target = platformTarget();
+  const baseUrl = releaseBaseUrl(repo, tag);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'helmor-npm-'));
+  const archivePath = path.join(tmpDir, target.asset);
+  const checksumsPath = path.join(tmpDir, 'checksums.txt');
+
+  try {
+    log(`Downloading ${target.asset} from ${repo}@${tag}`);
+    await downloadFile(`${baseUrl}/${target.asset}`, archivePath);
+    await downloadFile(`${baseUrl}/checksums.txt`, checksumsPath);
+
+    const expectedChecksum = checksumFor(fs.readFileSync(checksumsPath, 'utf8'), target.asset);
+    const actualChecksum = sha256(archivePath);
+    if (expectedChecksum !== actualChecksum) {
+      throw new Error(`checksum mismatch for ${target.asset}`);
+    }
+
+    extractArchive(archivePath, tmpDir, target);
+
+    fs.rmSync(vendorDir, { recursive: true, force: true });
+    fs.mkdirSync(vendorDir, { recursive: true });
+
+    const sourceBinary = path.join(tmpDir, target.executable);
+    const installedBinary = path.join(vendorDir, target.executable);
+    fs.copyFileSync(sourceBinary, installedBinary);
+
+    if (process.platform !== 'win32') {
+      fs.chmodSync(installedBinary, 0o755);
+    }
+
+    if (tag !== 'latest') {
+      verifyInstalledVersion(installedBinary, tag.replace(/^v/, ''));
+    }
+
+    log(`Installed helmor to ${installedBinary}`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err) => {
+  console.error(`helmor: ${err.message}`);
+  process.exit(1);
+});

package/scripts/lib.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const SUPPORTED_PLATFORMS = {
+  darwin: 'darwin',
+  linux: 'linux',
+  win32: 'windows'
+};
+
+function normalizeArch(arch) {
+  switch (arch) {
+    case 'arm64':
+      return 'arm64';
+    case 'x64':
+      return 'amd64';
+    default:
+      throw new Error(`unsupported architecture: ${arch}`);
+  }
+}
+
+function platformTarget(platform = process.platform, arch = process.arch) {
+  const goos = SUPPORTED_PLATFORMS[platform];
+  if (!goos) {
+    throw new Error(`unsupported platform: ${platform}`);
+  }
+
+  const goarch = normalizeArch(arch);
+  const archiveExt = platform === 'win32' ? 'zip' : 'tar.gz';
+  const executable = platform === 'win32' ? 'helmor.exe' : 'helmor';
+
+  return {
+    goos,
+    goarch,
+    archiveExt,
+    executable,
+    asset: `helmor_${goos}_${goarch}.${archiveExt}`
+  };
+}
+
+function tagFromVersion(version) {
+  if (!version) {
+    throw new Error('version is required');
+  }
+
+  if (version === 'latest' || version.startsWith('v')) {
+    return version;
+  }
+
+  return `v${version}`;
+}
+
+function releaseBaseUrl(repo, tag) {
+  if (!repo) {
+    throw new Error('repo is required');
+  }
+
+  if (tag === 'latest') {
+    return `https://github.com/${repo}/releases/latest/download`;
+  }
+
+  return `https://github.com/${repo}/releases/download/${tag}`;
+}
+
+function checksumFor(checksums, asset) {
+  for (const line of checksums.split(/\r?\n/)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length >= 2 && parts[parts.length - 1] === asset) {
+      return parts[0].toLowerCase();
+    }
+  }
+
+  throw new Error(`missing checksum for ${asset}`);
+}
+
+module.exports = {
+  checksumFor,
+  platformTarget,
+  releaseBaseUrl,
+  tagFromVersion
+};