@parcha/agentrun-cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# AgentRun npm launcher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@parcha/agentrun-cli` is a dependency-free Node.js launcher for the AgentRun Python CLI. It requires Node.js 20 or newer. The release manifest must explicitly verify the current Linux architecture; releases marked `libc: "glibc"` require glibc. macOS and Windows are not supported by this launcher release.
+
+```bash
+npx --yes --package https://github.com/Parcha-ai/agentrun/releases/download/cli-v0.1.10/parcha-agentrun-cli-0.1.1.tgz agentrun connect
+npx --yes --package https://github.com/Parcha-ai/agentrun/releases/download/cli-v0.1.10/parcha-agentrun-cli-0.1.1.tgz agentrun status
+```
+
+Launcher 0.1.1 defaults to CLI 0.1.10 from the public `Parcha-ai/agentrun` GitHub release tagged `cli-v0.1.10`. This default is pinned: it does not follow GitHub's latest release. `--cli-version <version>` selects the matching `cli-v<version>` tag. A completed default or explicitly pinned installation works offline without contacting the release server.
+
+Use `--source https://YOUR-CONSOLE/agentrun-cli` or `AGENTRUN_CLI_SOURCE` to override GitHub with an explicit release directory. Put launcher options before the CLI command; all arguments from the first CLI argument onward are forwarded unchanged. A leading `--` ends launcher option parsing. The Python CLI inherits stdin, stdout, stderr, and the current working directory, including terminal interaction.
+
+## Installation and reuse
+
+In default GitHub mode, the launcher downloads `release.json` and its named artifacts from `https://github.com/Parcha-ai/agentrun/releases/download/cli-v<version>/`. Each direct release-asset request may follow one redirect to exactly `https://release-assets.githubusercontent.com/`, with no credentials or explicit port. Other destinations and further redirects are refused.
+
+Explicit sources retain their own directory layout: `release.json` without a CLI version, or `releases/<version>.json` with `--cli-version`. All artifact filenames resolve in the selected source directory. Explicit sources refuse every redirect, including when the supplied source happens to be on GitHub.
+
+The launcher verifies the SHA-256 of the named CLI wheel, requirements file, and compressed `uv` bootstrap before executing the bootstrap. It also verifies the expanded bootstrap hash. Release artifacts must be plain filenames. HTTPS is required, and downloads have size and time limits. HTTP is accepted only for loopback addresses used in local verification.
+
+The verified `uv` executable provisions Python 3.12, synchronizes dependencies with `--require-hashes --only-binary :all:`, and installs the verified local CLI wheel without resolving additional dependencies. Initial installation therefore also requires access to the managed Python distribution and dependency index. Dependency consistency, CLI module import, and installed-version checks must pass before the installation is marked ready.
+
+Runtime files live under `~/.local/share/agentrun`, or the absolute directory named by `AGENTRUN_INSTALL_DIR`. This root must belong to the current user, have no group or other permissions, and must not be a symlink. Python distributions, dependency cache, and complete CLI environments remain outside the npm cache. Removing the npm cache does not remove the runtime used by the CLI or its background processes.
+
+Each source, platform, architecture, and manifest has a separate stable environment. The environment stays at its final path throughout installation. Concurrent installs of the same release are serialized. Completed installations are reused; old installations and their background processes are retained. The launcher runs Python with `-I` and clears Python path overrides and inherited installer configuration.
+
+Explicit-source invocations without `--cli-version` fetch the current manifest each time. Default GitHub invocations and explicitly pinned versions reuse their completed cached installation without a release-server connection. When using `npx`, npm may separately need network access to obtain the launcher package itself.
+
+## Recovery
+
+A failed installation removes only the directory created by that attempt, so the next invocation can retry. Hard termination can leave an incomplete environment or installation lock. The launcher reports its path and leaves it untouched. After confirming that no installation uses it, inspect and move the incomplete directory aside or remove the abandoned lock, then retry. The launcher does not kill other processes or automatically remove old environments.
+
+The launcher does not enable adapters, startup behavior, or other CLI consent choices. Existing CLI commands own those actions.
+
+## Local verification
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+The subprocess tests serve release fixtures over local HTTP and HTTPS servers and use a fixture executable at the external `uv` boundary. The HTTPS cases route sockets to loopback through a test-only Node agent preload while preserving the requested URLs, hostnames, SNI, and certificate verification. The test certificate and key are public fixture material, trusted only by those child processes; fixtures are excluded from the npm package. Tests cover GitHub pinning and redirect boundaries, checksums, source overrides, path validation, private roots, concurrent installation, failed-install retry, persistent and offline reuse, argument and stream forwarding, signals, and readiness checks. A real bootstrap/Python installation is a separate release acceptance check.

package/bin/agentrun.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, chmod, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import http from 'node:http';
+import https from 'node:https';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { gunzipSync } from 'node:zlib';
+
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const versionPattern = /^\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?(?:\.post\d+)?$/;
+const hashPattern = /^[a-f0-9]{64}$/;
+const defaultCliVersion = '0.1.10';
+const limits = { manifest: 512 * 1024, requirements: 8 * 1024 * 1024, artifact: 64 * 1024 * 1024, executable: 128 * 1024 * 1024 };
+let activeChild;
+let activeRequest;
+let receivedSignal;
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => {
+    receivedSignal ??= signal;
+    if (activeChild) activeChild.kill(signal);
+    if (activeRequest) activeRequest.destroy(new Error(`Interrupted by ${signal}`));
+  });
+}
+
+function interrupted() {
+  if (receivedSignal) throw new Error(`Interrupted by ${receivedSignal}`);
+}
+
+function options(args) {
+  let source = process.env.AGENTRUN_CLI_SOURCE;
+  let version;
+  let index = 0;
+  for (; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--') { index++; break; }
+    if (!/^--(?:source|cli-version)(?:=|$)/.test(arg)) break;
+    const equal = arg.indexOf('=');
+    const name = equal < 0 ? arg : arg.slice(0, equal);
+    const value = equal < 0 ? args[++index] : arg.slice(equal + 1);
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value`);
+    if (name === '--source') source = value;
+    else version = value;
+  }
+  if (version && !versionPattern.test(version)) throw new Error('Invalid --cli-version');
+  const github = !source;
+  if (github) {
+    version ??= defaultCliVersion;
+    source = `https://github.com/Parcha-ai/agentrun/releases/download/cli-v${version}/`;
+  }
+  return { source: releaseSource(source), version, github, args: args.slice(index) };
+}
+
+function releaseSource(value) {
+  if (/[\\%?#\s]/.test(value) || /(?:^|\/)\.{1,2}(?:\/|$)/.test(value)) throw new Error('Invalid release source URL');
+  const url = new URL(value);
+  const loopback = url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !loopback) || url.username || url.password) throw new Error('Release source must use HTTPS (HTTP is allowed only on loopback) without credentials');
+  if (!/^\/[A-Za-z0-9_./~-]*$/.test(url.pathname)) throw new Error('Invalid release source path');
+  url.pathname = url.pathname.replace(/\/+$/, '') + '/';
+  return url.href;
+}
+
+function artifact(value, label) {
+  if (!value || typeof value !== 'object' || typeof value.filename !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value.filename) || typeof value.sha256 !== 'string' || !hashPattern.test(value.sha256)) {
+    throw new Error(`Invalid ${label} filename or SHA-256`);
+  }
+  return value;
+}
+
+function manifestFrom(bytes, expectedVersion) {
+  const m = JSON.parse(bytes.toString('utf8'));
+  if (m.launcher_schema !== 1 || !versionPattern.test(m.version) || (expectedVersion && m.version !== expectedVersion)) throw new Error('Unsupported or mismatched release manifest version');
+  if (m.python_version !== '3.12' || typeof m.requires_python !== 'string') throw new Error('Unsupported Python release requirement');
+  if (process.platform !== 'linux' || !Array.isArray(m.verified_os) || !m.verified_os.includes(process.platform)) throw new Error('This release is not verified for this operating system');
+  artifact(m, 'wheel');
+  if (m.filename !== `agentrun_cli-${m.version}-py3-none-any.whl`) throw new Error('Invalid CLI wheel filename');
+  artifact(m.requirements, 'requirements');
+  if (m.requirements.filename !== `requirements-${m.requirements.sha256}.txt`) throw new Error('Invalid requirements filename');
+  const bootstrap = artifact(m.bootstrap?.[`${process.platform}-${process.arch}`], 'platform bootstrap');
+  if (!/^uv-\d+\.\d+\.\d+-linux-(?:x64|arm64)\.gz$/.test(bootstrap.filename) || !hashPattern.test(bootstrap.uncompressed_sha256)) throw new Error('Invalid bootstrap archive');
+  if (bootstrap.libc === 'glibc' && !process.report.getReport().header.glibcVersionRuntime) throw new Error('This release requires glibc; musl/Alpine is not supported');
+  if (bootstrap.libc !== undefined && bootstrap.libc !== 'glibc') throw new Error('Unsupported bootstrap libc');
+  return m;
+}
+
+function githubRedirect(url, location) {
+  const asset = /^https:\/\/github\.com\/Parcha-ai\/agentrun\/releases\/download\/cli-v([^/]+)\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.exec(url);
+  if (!asset || !versionPattern.test(asset[1]) || typeof location !== 'string' || !location.startsWith('https://release-assets.githubusercontent.com/') || /[\\\s#]/.test(location)) {
+    throw new Error('Release redirect rejected: only the pinned GitHub release asset CDN is allowed');
+  }
+  const target = new URL(location);
+  if (target.protocol !== 'https:' || target.hostname !== 'release-assets.githubusercontent.com' || target.port || target.username || target.password || target.hash) {
+    throw new Error('Release redirect rejected: invalid GitHub asset CDN URL');
+  }
+  return target.href;
+}
+
+function download(url, maxBytes, allowGithubRedirect = false) {
+  interrupted();
+  return new Promise((resolveDownload, reject) => {
+    const client = url.startsWith('https:') ? https : http;
+    const request = client.get(url, { headers: { 'Accept-Encoding': 'identity' } }, (response) => {
+      response.on('error', reject);
+      if (allowGithubRedirect && [301, 302, 303, 307, 308].includes(response.statusCode)) {
+        try {
+          const destination = githubRedirect(url, response.headers.location);
+          response.resume();
+          request.destroy();
+          resolveDownload(download(destination, maxBytes));
+        } catch (error) { request.destroy(error); }
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        request.destroy(new Error(`Release download rejected HTTP ${response.statusCode}; redirects are not allowed`));
+        return;
+      }
+      if (Number(response.headers['content-length']) > maxBytes) {
+        request.destroy(new Error('Release download exceeds size limit'));
+        return;
+      }
+      let size = 0;
+      const chunks = [];
+      response.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) request.destroy(new Error('Release download exceeds size limit'));
+        else chunks.push(chunk);
+      });
+      response.on('end', () => resolveDownload(Buffer.concat(chunks)));
+    });
+    activeRequest = request;
+    const timer = setTimeout(() => request.destroy(new Error('Release download timed out')), 60_000);
+    request.on('error', reject);
+    request.on('close', () => { clearTimeout(timer); if (activeRequest === request) activeRequest = undefined; });
+  });
+}
+
+async function verifiedDownload(source, spec, maxBytes, allowGithubRedirect) {
+  const bytes = await download(new URL(spec.filename, source).href, maxBytes, allowGithubRedirect);
+  if (sha256(bytes) !== spec.sha256) throw new Error(`SHA-256 verification failed for ${spec.filename}`);
+  return bytes;
+}
+
+async function privateDirectory(path) {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  const stat = await lstat(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid())) {
+    throw new Error(`Installation directory must be private, owned by you, and not a symlink: ${path}`);
+  }
+}
+
+async function atomicWrite(path, bytes) {
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, bytes, { mode: 0o600, flag: 'wx' });
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
+function childEnvironment(root) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('UV_') || key.startsWith('PIP_') || ['PYTHONPATH', 'PYTHONHOME', 'VIRTUAL_ENV', 'CONDA_PREFIX'].includes(key)) delete env[key];
+  }
+  return { ...env, UV_PYTHON_INSTALL_DIR: join(root, 'python'), UV_CACHE_DIR: join(root, 'cache') };
+}
+
+function runChild(command, args, env, cwd, stdio = 'inherit') {
+  interrupted();
+  return new Promise((resolveChild, reject) => {
+    activeChild = spawn(command, args, { env, cwd, stdio, shell: false });
+    activeChild.on('error', (error) => { activeChild = undefined; reject(error); });
+    activeChild.on('exit', (code, signal) => { activeChild = undefined; resolveChild({ code, signal }); });
+  });
+}
+
+async function withLock(lock, action) {
+  const deadline = Date.now() + 120_000;
+  for (;;) {
+    interrupted();
+    try {
+      await mkdir(lock, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      await privateDirectory(lock);
+      if (Date.now() >= deadline) throw new Error(`Another installation holds ${lock}. If its process has stopped, remove this lock directory and retry.`);
+      await delay(150);
+    }
+  }
+  try { return await action(); }
+  finally { await rm(lock, { recursive: true, force: true }); }
+}
+
+async function ready(install, identity) {
+  try {
+    const receipt = JSON.parse(await readFile(join(install, 'ready.json'), 'utf8'));
+    if (receipt.identity !== identity) return false;
+    await access(join(install, 'venv', 'bin', 'python'), constants.X_OK);
+    return true;
+  } catch (error) {
+    if (['ENOENT', 'EACCES'].includes(error.code) || error instanceof SyntaxError) return false;
+    throw error;
+  }
+}
+
+async function installRelease(root, source, sourceRoot, manifestBytes, manifest, allowGithubRedirect) {
+  const identity = sha256(Buffer.concat([Buffer.from(`${process.platform}-${process.arch}\n${source}\n`), manifestBytes]));
+  const installs = join(sourceRoot, 'installs');
+  await privateDirectory(installs);
+  const install = join(installs, `${manifest.version}-${identity}`);
+  const python = join(install, 'venv', 'bin', 'python');
+  await withLock(`${install}.lock`, async () => {
+    let created = false;
+    try {
+      try { await mkdir(install, { mode: 0o700 }); created = true; }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        await privateDirectory(install);
+        if (await ready(install, identity)) return;
+        throw new Error(`An incomplete installation already exists at ${install}. Inspect it and move it aside before retrying; existing runtimes are not removed automatically.`);
+      }
+      const spec = manifest.bootstrap[`${process.platform}-${process.arch}`];
+      const compressed = await verifiedDownload(source, spec, limits.artifact, allowGithubRedirect);
+      const uv = gunzipSync(compressed, { maxOutputLength: limits.executable });
+      if (sha256(uv) !== spec.uncompressed_sha256) throw new Error('SHA-256 verification failed for uncompressed bootstrap');
+      const uvPath = join(install, 'uv');
+      await writeFile(uvPath, uv, { mode: 0o700, flag: 'wx' });
+      await chmod(uvPath, 0o700);
+      const requirements = await verifiedDownload(source, manifest.requirements, limits.requirements, allowGithubRedirect);
+      const requirementsPath = join(install, manifest.requirements.filename);
+      await writeFile(requirementsPath, requirements, { mode: 0o600, flag: 'wx' });
+      const wheel = await verifiedDownload(source, manifest, limits.artifact, allowGithubRedirect);
+      const wheelPath = join(install, manifest.filename);
+      await writeFile(wheelPath, wheel, { mode: 0o600, flag: 'wx' });
+      const env = childEnvironment(root);
+      for (const args of [
+        ['venv', '--no-project', '--managed-python', '--python', manifest.python_version, join(install, 'venv')],
+        ['pip', 'sync', '--require-hashes', '--only-binary', ':all:', '--python', python, requirementsPath],
+        ['pip', 'install', '--no-deps', '--no-index', '--python', python, wheelPath],
+        ['pip', 'check', '--python', python],
+      ]) {
+        const result = await runChild(uvPath, ['--no-config', ...args], env, root);
+        if (result.code !== 0) throw new Error(`Runtime installation failed (${result.signal ?? result.code})`);
+      }
+      await access(python, constants.X_OK);
+      const smoke = await runChild(python, ['-I', '-c', `import agentrun_cli.cli; from importlib.metadata import version; assert version("agentrun-cli") == ${JSON.stringify(manifest.version)}`], env, root, ['ignore', 'ignore', 'inherit']);
+      if (smoke.code !== 0) throw new Error('Installed CLI did not pass the version and import check');
+      interrupted();
+      await atomicWrite(join(install, 'ready.json'), JSON.stringify({ identity, source, version: manifest.version }));
+    } catch (error) {
+      if (created) await rm(install, { recursive: true, force: true });
+      throw error;
+    }
+  });
+  return python;
+}
+
+async function main() {
+  const opts = options(process.argv.slice(2));
+  if (process.platform !== 'linux') throw new Error('The launcher currently supports verified Linux releases only');
+  const configuredRoot = process.env.AGENTRUN_INSTALL_DIR ?? join(homedir(), '.local', 'share', 'agentrun');
+  if (!isAbsolute(configuredRoot)) throw new Error('AGENTRUN_INSTALL_DIR must be an absolute path');
+  const root = resolve(configuredRoot);
+  await privateDirectory(root);
+  for (const folder of ['python', 'cache', 'sources']) await privateDirectory(join(root, folder));
+  const sourceRoot = join(root, 'sources', sha256(opts.source));
+  await privateDirectory(sourceRoot);
+  const manifests = join(sourceRoot, 'manifests');
+  await privateDirectory(manifests);
+  let bytes;
+  const cachePath = opts.version ? join(manifests, `${opts.version}.json`) : undefined;
+  if (cachePath) {
+    try { bytes = await readFile(cachePath); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  bytes ??= await download(new URL(!opts.github && opts.version ? `releases/${opts.version}.json` : 'release.json', opts.source).href, limits.manifest, opts.github);
+  const manifest = manifestFrom(bytes, opts.version);
+  const python = await installRelease(root, opts.source, sourceRoot, bytes, manifest, opts.github);
+  await atomicWrite(join(manifests, `${manifest.version}.json`), bytes);
+  const result = await runChild(python, ['-I', '-m', 'agentrun_cli', ...opts.args], childEnvironment(root));
+  if (result.signal) receivedSignal ??= result.signal;
+  else process.exitCode = result.code ?? 1;
+}
+
+try { await main(); }
+catch (error) { console.error(`agentrun: ${error.message}`); process.exitCode = 1; }
+if (receivedSignal) {
+  process.removeAllListeners(receivedSignal);
+  process.kill(process.pid, receivedSignal);
+}

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@parcha/agentrun-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Verified, persistent launcher for the AgentRun Python CLI",
+  "type": "module",
+  "bin": { "agentrun": "bin/agentrun.mjs" },
+  "files": ["bin/agentrun.mjs", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "license": "UNLICENSED"
+}