@zergai/cyberdeck 0.2.0-beta.1 → 0.2.1-dev.35760740177

package/README.md

@@ -282,3 +282,20 @@ response is provisioning, not execution success or evidence readiness. Keep its
 exact run ID/URL; inspect `run-show` for execution, artifact status, expiry, and
 authorized download URLs. Evaluator access remains enforced by the server.
 Control commands request a state change; inspect the run to confirm it happened.
+
+## Updating the npm CLI
+
+Run `zcd update` or `zcd --update` to install a newer npm
+release. `zcd update --check` prints JSON without installing. The
+installed channel is preserved (`dev`, `next`, or `latest`); select a channel
+explicitly with `update --channel dev|next|latest`. Updates never downgrade.
+
+Startup checks only notify on stderr when it is a terminal, never prompt or
+install, and are cached for one hour. CI, redirected stderr, and help/version
+requests skip checks. Set `ZERGAI_NO_UPDATE_CHECK=1` to disable startup checks.
+Self-installation requires the matching macOS/Linux global npm prefix; local,
+linked, npx, or other package-manager installs must use their original manager.
+Existing releases need one ordinary npm upgrade before these commands exist.
+
+See [shared updater policy](https://github.com/Epoch-ML/zerg/blob/development/docs/npm-cli-updates.md)
+for installation safety, channel switching, and packaging details.

package/npm-cli/npm-process.cjs

@@ -0,0 +1,21 @@
+'use strict';
+const { execFile, spawn } = require('node:child_process');
+const { promisify } = require('node:util');
+
+// Kept separate so OS process contracts can be exercised independently from the
+// version/cache policy. This is copied alongside the updater in each artifact.
+module.exports = async function runNpm(args, options) {
+  if (args[0] === 'prefix') return promisify(execFile)('npm', args, { ...options, encoding: 'utf8', timeout: 5000, maxBuffer: 16384 });
+  await new Promise((done, fail) => {
+    const child = spawn('npm', args, { ...options, stdio: ['ignore', 'inherit', 'inherit'], shell: false });
+    // npm shares the foreground group; a terminal has already signalled it.
+    const relay = ![process.stdin, process.stdout, process.stderr].some(stream => stream.isTTY);
+    const interrupt = () => { if (relay) child.kill('SIGINT'); };
+    const terminate = () => { if (relay) child.kill('SIGTERM'); };
+    process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+    const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
+    child.on('error', error => { cleanup(); fail(error); });
+    child.on('exit', (code, signal) => { cleanup(); if (code === 0) done(); else fail(new Error(`npm exited ${signal || code}`)); });
+  });
+  return { stdout: '' };
+};

package/npm-cli/run.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+const { spawn } = require('node:child_process');
+const { join } = require('node:path');
+const { handleUpdate } = require('./update.cjs');
+
+async function main() {
+  const root = join(__dirname, '..');
+  const args = process.argv.slice(2);
+  const result = await handleUpdate({ root, args });
+  if (result !== null) { process.exitCode = result; return; }
+  if (args.length === 1 && ['--help', '-h', 'help'].includes(args[0])) {
+    process.stdout.write('Updates: update | --update [--check] [--channel dev|next|latest]\n');
+  }
+  const metadata = require('../package.json');
+  // ZTC's old TUI updaters must not install silently behind this launch policy.
+  const env = { ...process.env };
+  if (['@zergai/ztc', 'zerg-ztc'].includes(metadata.name)) {
+    env.ZTC_NO_AUTO_UPDATE = '1'; env.ZTC_DISABLE_UPDATE = '1';
+  }
+  const child = spawn(process.execPath, [join(root, metadata.zergCli.entry), ...args], { stdio: 'inherit', env });
+  // Attached terminals signal the foreground group, including the child. Relay
+  // only for non-TTY supervisors; keep the group intact for terminal resize.
+  const relay = ![process.stdin, process.stdout, process.stderr].some(stream => stream.isTTY);
+  const interrupt = () => { if (relay) child.kill('SIGINT'); };
+  const terminate = () => { if (relay) child.kill('SIGTERM'); };
+  process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+  const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
+  child.on('error', error => { cleanup(); console.error(`Unable to launch ${metadata.name}: ${error.message}`); process.exitCode = 1; });
+  child.on('exit', (code, signal) => {
+    cleanup();
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/npm-cli/update.cjs

@@ -0,0 +1,161 @@
+'use strict';
+
+// Copied into each npm CLI at pack time. No repo paths or runtime dependencies.
+const runNpm = require('./npm-process.cjs');
+const { readFile, realpath, lstat, mkdir, mkdtemp, writeFile, rename, rm } = require('node:fs/promises');
+const { homedir } = require('node:os');
+const { join, resolve, isAbsolute } = require('node:path');
+const registry = 'https://registry.npmjs.org';
+const cacheLifetime = 60 * 60 * 1000;
+
+function parseVersion(version) {
+  const match = typeof version === 'string' && version.length <= 256 && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(version);
+  if (!match || match.slice(1, 4).some(n => !Number.isSafeInteger(Number(n))) || (match[4] || '').split('.').some(n => /^0\d+$/.test(n))) {
+    throw new Error('Invalid semantic version');
+  }
+  return { core: match.slice(1, 4).map(Number), pre: match[4] ? match[4].split('.') : [] };
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left), b = parseVersion(right);
+  for (let i = 0; i < 3; i++) if (a.core[i] !== b.core[i]) return a.core[i] > b.core[i] ? 1 : -1;
+  if (!a.pre.length && b.pre.length) return 1;
+  if (a.pre.length && !b.pre.length) return -1;
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === b.pre[i]) continue;
+    if (a.pre[i] === undefined) return -1;
+    if (b.pre[i] === undefined) return 1;
+    const an = /^\d+$/.test(a.pre[i]), bn = /^\d+$/.test(b.pre[i]);
+    if (an !== bn) return an ? -1 : 1;
+    return (an ? BigInt(a.pre[i]) > BigInt(b.pre[i]) : a.pre[i] > b.pre[i]) ? 1 : -1;
+  }
+  return 0;
+}
+
+function releaseChannel(version) {
+  const { pre } = parseVersion(version);
+  return pre[0] === 'dev' ? 'dev' : pre.length ? 'next' : 'latest';
+}
+
+function identity(metadata) {
+  if (!/^@zergai\/[a-z0-9][a-z0-9-]*$/.test(metadata.name) && !['zerg-ztc', 'zerg-cyberdeck'].includes(metadata.name)) {
+    throw new Error('Unsupported CLI package identity');
+  }
+  parseVersion(metadata.version);
+}
+
+async function checkUpdate(metadata, { fetch = globalThis.fetch, channel = releaseChannel(metadata.version), timeoutMs = 5000 } = {}) {
+  identity(metadata);
+  if (!['dev', 'next', 'latest'].includes(channel)) throw new Error('Invalid update channel');
+  const response = await fetch(`${registry}/${encodeURIComponent(metadata.name)}/${channel}`, {
+    headers: { Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) throw new Error(`npm registry check failed (${response.status})`);
+  const reader = response.body.getReader();
+  const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 1024 * 1024) throw new Error('npm registry response too large');
+      chunks.push(Buffer.from(value));
+    }
+  } finally { await reader.cancel(); }
+  const data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (data.name !== metadata.name) throw new Error('npm registry package identity mismatch');
+  if (releaseChannel(data.version) !== channel) throw new Error('npm registry version does not match the requested channel');
+  return { name: metadata.name, current: metadata.version, latest: data.version, channel, hasUpdate: compareVersions(data.version, metadata.version) > 0 };
+}
+
+function updateOptions(args) {
+  const options = { check: false };
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--check' && !options.check) options.check = true;
+    else if (arg === '--channel' && !options.channel && ['dev', 'next', 'latest'].includes(args[i + 1])) options.channel = args[++i];
+    else if (['--help', '-h'].includes(arg) && args.length === 2) options.help = true;
+    else throw new Error('Usage: update [--check] [--channel dev|next|latest]');
+  }
+  return options;
+}
+
+async function install(root, metadata, info, npm, env) {
+  const { stdout } = await npm(['prefix', '--global'], { env });
+  const prefix = stdout.trim();
+  if (!isAbsolute(prefix)) throw new Error('Cannot identify the global npm installation');
+  const expected = join(prefix, 'lib/node_modules', metadata.name);
+  // Compare real paths AND reject npm link. Never turn npx/local/checkouts into a
+  // global install or update a different Node-version manager's global prefix.
+  const matches = await (async () => !(await lstat(expected)).isSymbolicLink() && await realpath(root) === await realpath(expected))().catch(() => false);
+  if (!matches) {
+    throw new Error('Not this global npm installation. Update using the package manager/prefix that installed this CLI.');
+  }
+  await npm(['install', '--global', '--prefix', prefix, `--registry=${registry}`, `--@zergai:registry=${registry}`, '--no-audit', '--no-fund', `${metadata.name}@${info.latest}`], { cwd: prefix, env });
+  const installed = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  if (installed.name !== metadata.name || installed.version !== info.latest) throw new Error('npm did not install the requested package version');
+}
+
+async function startupCheck(metadata, env, fetch) {
+  const channel = releaseChannel(metadata.version);
+  const directory = join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'zergai-cli-updates');
+  const path = join(directory, `${encodeURIComponent(metadata.name)}-${channel}.json`);
+  try {
+    const cached = JSON.parse(await readFile(path, 'utf8'));
+    const age = Date.now() - cached.checkedAt;
+    if (Number.isFinite(age) && age >= 0 && age < cacheLifetime && cached.current === metadata.version) {
+      if (cached.latest === null) return null;
+      if (releaseChannel(cached.latest) === channel) return { latest: cached.latest, hasUpdate: compareVersions(cached.latest, metadata.version) > 0 };
+    }
+  } catch { /* Missing, stale, or malformed cache: do a bounded public check. */ }
+  let info = null;
+  try { info = await checkUpdate(metadata, { fetch, timeoutMs: 800 }); }
+  catch { /* A registry outage must not prevent use of a CLI. */ }
+  let staging;
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    staging = await mkdtemp(join(directory, '.check-'));
+    const source = join(staging, 'record');
+    await writeFile(source, JSON.stringify({ current: metadata.version, latest: info?.latest ?? null, checkedAt: Date.now() }), { flag: 'wx', mode: 0o600 });
+    await rename(source, path);
+  } catch { /* Read-only home/cache is supported. */ }
+  finally { if (staging) await rm(staging, { recursive: true, force: true }).catch(() => {}); }
+  return info;
+}
+
+async function handleUpdate({ root, args, env = process.env, stdout = process.stdout, stderr = process.stderr, fetch = globalThis.fetch, npm = runNpm }) {
+  const explicit = ['update', '--update'].includes(args[0]);
+  if (!explicit && (env.CI || env.ZERGAI_NO_UPDATE_CHECK === '1' || !stderr.isTTY || args.some(arg => ['help', '--help', '-h', 'version', '--version', '-V'].includes(arg)))) return null;
+  let options;
+  try { options = explicit ? updateOptions(args) : {}; }
+  catch (error) { stderr.write(`${error.message}\n`); return 2; }
+  if (options.help) {
+    stdout.write('Check npm and update this globally installed CLI\nUsage: update | --update [--check] [--channel dev|next|latest]\n--check prints JSON without installing. Channels are preserved by default.\nStartup only notifies; set ZERGAI_NO_UPDATE_CHECK=1 to disable checks.\n');
+    return 0;
+  }
+  try {
+    const metadata = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    identity(metadata);
+    if (!explicit) {
+      const info = await startupCheck(metadata, env, fetch);
+      if (info?.hasUpdate) stderr.write(`Update available for ${metadata.name}: ${metadata.version} → ${info.latest}. Run ${Object.keys(metadata.bin || {})[0] || metadata.name} update.\n`);
+      return null;
+    }
+    // Explicit checks/install always consult the registry; cache is advisory only.
+    const info = await checkUpdate(metadata, { fetch, ...options });
+    if (options.check) stdout.write(`${JSON.stringify(info)}\n`);
+    else if (!info.hasUpdate) stderr.write(`No newer ${info.channel} release of ${metadata.name} (installed ${metadata.version}).\n`);
+    else {
+      stderr.write(`Updating ${metadata.name}: ${metadata.version} → ${info.latest} (${info.channel})…\n`);
+      await install(resolve(root), metadata, info, npm, env);
+      stderr.write(`Updated ${metadata.name} to ${info.latest}. The next launch uses the new version.\n`);
+    }
+    return 0;
+  } catch (error) {
+    if (!explicit) return null;
+    stderr.write(`Update failed: ${error.message}\n`);
+    return 1;
+  }
+}
+
+module.exports = { compareVersions, releaseChannel, checkUpdate, handleUpdate };

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@zergai/cyberdeck",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.1-dev.35760740177",
   "description": "Command-line client for Zerg CyberDeck clone environments and server-side SDK conformance runs.",
   "type": "module",
+  "zergCli": {
+    "entry": "dist/index.js"
+  },
   "bin": {
-    "zcd": "dist/index.js"
+    "zcd": "npm-cli/run.cjs"
   },
   "files": [
+    "npm-cli/*.cjs",
     "dist/**/*.js",
     "README.md",
     "LICENSE.md",
@@ -36,12 +40,12 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "dev"
   },
   "scripts": {
     "build": "tsc --build --force",
     "clean": "tsc --build --clean",
-    "prepack": "npm run clean && npm run build",
+    "prepack": "npm run clean && npm run build && node ../../../scripts/npm/prepare-cli.mjs",
     "test:public-tarball": "node scripts/smoke-packed-public-api.mjs"
   },
   "dependencies": {
@@ -49,9 +53,9 @@
     "socket.io-client": "^4.8.1"
   },
   "zergRelease": {
-    "branch": "main",
-    "channel": "next",
-    "sourceCommit": "3b288334492cd150a61ed06610cd2b5ad546c81b",
+    "branch": "development",
+    "channel": "dev",
+    "sourceCommit": "4b068dffbc8a4dd0debe7e14c61674e5d4670ff4",
     "sourceVersion": "0.1.0-beta.1"
   }
 }