@caelis/caelis 0.28.0 → 0.30.0

package/bin/caelis.js

@@ -4,6 +4,13 @@ const { spawn } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 
+const {
+  UpdateHandoffError,
+  completeHandoff,
+  handoffEnvironment,
+  reserveHandoffDirectory,
+} = require('../lib/update-handoff.js');
+
 const packageMap = {
   'darwin:arm64': '@caelis/caelis-darwin-arm64',
   'darwin:x64': '@caelis/caelis-darwin-x64',
@@ -13,60 +20,287 @@ const packageMap = {
   'win32:x64': '@caelis/caelis-windows-x64',
 };
 
-function resolvePackageName() {
-  const key = `${process.platform}:${process.arch}`;
+const signalForwardGraceMs = 5000;
+
+class LauncherError extends Error {
+  constructor(lines) {
+    const normalized = Array.isArray(lines) ? lines : [String(lines || '')];
+    super(normalized.join('\n'));
+    this.name = 'LauncherError';
+    this.lines = normalized;
+  }
+}
+
+function resolvePackageName(platform = process.platform, arch = process.arch) {
+  const key = `${platform}:${arch}`;
   const packageName = packageMap[key];
   if (!packageName) {
-    console.error(`[caelis] unsupported platform/arch: ${process.platform}/${process.arch}`);
-    process.exit(1);
+    throw new Error(`unsupported platform/arch: ${platform}/${arch}`);
   }
   return packageName;
 }
 
-function resolveBinaryPath(packageName) {
+function resolveBinaryPath(
+  packageName,
+  platform = process.platform,
+  resolver = require.resolve,
+) {
+  let packageJsonPath;
   try {
-    const packageJsonPath = require.resolve(`${packageName}/package.json`);
-    const binaryName = process.platform === 'win32' ? 'caelis.exe' : 'caelis';
-    return path.join(path.dirname(packageJsonPath), 'runtime', binaryName);
+    packageJsonPath = resolver(`${packageName}/package.json`);
   } catch (err) {
-    console.error(`[caelis] platform package not installed: ${packageName}`);
-    console.error('[caelis] reinstall without --omit=optional, then try again.');
-    console.error('[caelis] resolve error:', err.message);
-    process.exit(1);
+    throw new LauncherError([
+      `platform package not installed: ${packageName}`,
+      'reinstall without --omit=optional, then try again',
+      `resolve error: ${err.message}`,
+    ]);
+  }
+  const binaryName = platform === 'win32' ? 'caelis.exe' : 'caelis';
+  return path.join(path.dirname(packageJsonPath), 'runtime', binaryName);
+}
+
+function handoffEligible(platform, argv, stdinIsTTY) {
+  if (platform !== 'win32') {
+    return false;
+  }
+  const first = String(argv[0] || '').trim().toLowerCase();
+  if (first === 'update') {
+    return !argv.some((value) => value === '--check' || value === '-check');
   }
+  const nonInteractiveCommands = new Set([
+    'version',
+    'acp',
+    'doctor',
+    'serve',
+    'server',
+    'sandbox',
+  ]);
+  if (nonInteractiveCommands.has(first) ||
+      argv.some((value) => value === '--doctor' || value === '-doctor')) {
+    return false;
+  }
+  if (argv.some((value) =>
+    value === '--interactive' || value === '-interactive')) {
+    return true;
+  }
+  const hasPrompt = argv.some((value, index) => {
+    if (value === '-p') {
+      return index + 1 < argv.length && String(argv[index + 1]).trim() !== '';
+    }
+    return String(value).startsWith('-p=') &&
+      String(value).slice(3).trim() !== '';
+  });
+  if (hasPrompt) {
+    return false;
+  }
+  return Boolean(stdinIsTTY);
 }
 
-const packageName = resolvePackageName();
-const binPath = resolveBinaryPath(packageName);
-const packageRoot = path.resolve(__dirname, '..');
-const platformPackageRoot = path.dirname(require.resolve(`${packageName}/package.json`));
+function formatLauncherError(err) {
+  if (err instanceof UpdateHandoffError) {
+    return `[caelis] update failed: ${err.message}`;
+  }
+  if (err instanceof LauncherError) {
+    return err.lines.map((line) => `[caelis] ${line}`).join('\n');
+  }
+  return `[caelis] ${err && err.message ? err.message : String(err)}`;
+}
+
+function createSignalCoordinator(target = process, options = {}) {
+  const forceKillAfterMs = options.forceKillAfterMs === undefined
+    ? signalForwardGraceMs
+    : options.forceKillAfterMs;
+  const handlers = new Map();
+  let activeChild;
+  let forceKillTimer;
+  let signal;
+
+  function clearForceKillTimer() {
+    if (forceKillTimer) {
+      clearTimeout(forceKillTimer);
+      forceKillTimer = undefined;
+    }
+  }
+
+  function forwardSignal() {
+    if (!signal || !activeChild) {
+      return;
+    }
+    try {
+      activeChild.kill(signal);
+    } catch {
+      // Still arm the hard-stop fallback below.
+    }
+    clearForceKillTimer();
+    if (forceKillAfterMs < 0) {
+      return;
+    }
+    forceKillTimer = setTimeout(() => {
+      if (!activeChild) {
+        return;
+      }
+      try {
+        activeChild.kill('SIGKILL');
+      } catch {
+        // The child may have exited between the timer check and kill.
+      }
+    }, forceKillAfterMs);
+    if (typeof forceKillTimer.unref === 'function') {
+      forceKillTimer.unref();
+    }
+  }
 
-if (!fs.existsSync(binPath)) {
-  console.error('[caelis] binary not found at', binPath);
-  console.error(`[caelis] reinstall ${packageName}, then try again.`);
-  process.exit(1);
+  for (const name of ['SIGINT', 'SIGTERM']) {
+    const handler = () => {
+      if (!signal) {
+        signal = name;
+      }
+      forwardSignal();
+    };
+    handlers.set(name, handler);
+    target.on(name, handler);
+  }
+
+  return {
+    receivedSignal() {
+      return signal;
+    },
+    track(child) {
+      activeChild = child;
+      forwardSignal();
+      let released = false;
+      return () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        if (activeChild === child) {
+          activeChild = undefined;
+          clearForceKillTimer();
+        }
+      };
+    },
+    close() {
+      clearForceKillTimer();
+      activeChild = undefined;
+      for (const [name, handler] of handlers) {
+        target.removeListener(name, handler);
+      }
+      handlers.clear();
+    },
+  };
 }
 
-const child = spawn(binPath, process.argv.slice(2), {
-  stdio: 'inherit',
-  env: {
+function runProcess(command, args, options = {}) {
+  const { signalCoordinator, ...spawnOptions } = options;
+  const pendingSignal = signalCoordinator && signalCoordinator.receivedSignal();
+  if (pendingSignal) {
+    return Promise.resolve({ code: 1, signal: pendingSignal });
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, spawnOptions);
+    let releaseChild = () => {};
+    child.once('error', (err) => {
+      releaseChild();
+      reject(err);
+    });
+    child.once('exit', (code, signal) => {
+      releaseChild();
+      resolve({ code: code === null ? 1 : code, signal });
+    });
+    if (signalCoordinator) {
+      releaseChild = signalCoordinator.track(child);
+    }
+  });
+}
+
+async function main() {
+  const platform = process.platform;
+  const packageName = resolvePackageName(platform, process.arch);
+  const binPath = resolveBinaryPath(packageName, platform);
+  const packageRoot = path.resolve(__dirname, '..');
+  const platformPackageRoot = path.dirname(path.dirname(binPath));
+
+  if (!fs.existsSync(binPath)) {
+    throw new LauncherError([
+      `binary not found at ${binPath}`,
+      `reinstall ${packageName}, then try again`,
+    ]);
+  }
+
+  const argv = process.argv.slice(2);
+  // The TUI can request an update after startup, so eligibility cannot be
+  // based only on an explicit `update` argv. Reserving a path does no
+  // filesystem I/O; Go creates it lazily only for an actual handoff.
+  const handoffDir = handoffEligible(platform, argv, process.stdin.isTTY)
+    ? reserveHandoffDirectory(platform)
+    : '';
+  const signalCoordinator = handoffDir
+    ? createSignalCoordinator()
+    : undefined;
+  const env = {
     ...process.env,
     CAELIS_INSTALL_METHOD: 'npm',
     CAELIS_NPM_PACKAGE_DIR: packageRoot,
     CAELIS_NPM_PLATFORM_PACKAGE: packageName,
     CAELIS_NPM_PLATFORM_PACKAGE_DIR: platformPackageRoot,
-  },
-});
+  };
+  if (handoffDir) {
+    env[handoffEnvironment] = handoffDir;
+  }
+  try {
+    let childResult = await runProcess(binPath, argv, {
+      stdio: 'inherit',
+      env,
+      signalCoordinator,
+    });
+    const receivedSignal = signalCoordinator && signalCoordinator.receivedSignal();
+    if (receivedSignal && !childResult.signal) {
+      childResult = { code: 1, signal: receivedSignal };
+    }
+    const result = await completeHandoff(handoffDir, childResult, {
+      signalCoordinator,
+    });
+    const finalSignal = signalCoordinator && signalCoordinator.receivedSignal();
+    if (finalSignal) {
+      return { code: 1, signal: finalSignal };
+    }
+    return result;
+  } catch (err) {
+    const receivedSignal = signalCoordinator && signalCoordinator.receivedSignal();
+    if (receivedSignal) {
+      return { code: 1, signal: receivedSignal };
+    }
+    throw err;
+  } finally {
+    if (signalCoordinator) {
+      signalCoordinator.close();
+    }
+  }
+}
 
-child.on('error', (err) => {
-  console.error('[caelis] failed to start binary:', err.message);
-  process.exit(1);
-});
+if (require.main === module) {
+  main()
+    .then((result) => {
+      if (result.signal) {
+        process.kill(process.pid, result.signal);
+        return;
+      }
+      process.exit(result.code);
+    })
+    .catch((err) => {
+      console.error(formatLauncherError(err));
+      process.exit(1);
+    });
+}
 
-child.on('exit', (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code === null ? 1 : code);
-});
+module.exports = {
+  LauncherError,
+  createSignalCoordinator,
+  formatLauncherError,
+  handoffEligible,
+  main,
+  resolveBinaryPath,
+  resolvePackageName,
+  runProcess,
+};

package/lib/update-handoff.js

@@ -0,0 +1,351 @@
+const { spawn } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const handoffEnvironment = 'CAELIS_NPM_UPDATE_HANDOFF_DIR';
+const handoffOwnershipName = 'ownership.json';
+const handoffPlanName = 'plan.json';
+const capturedOutputLimit = 64 * 1024;
+
+class UpdateHandoffError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = 'UpdateHandoffError';
+  }
+}
+
+function appendCaptured(previous, chunk) {
+  const next = previous + chunk.toString();
+  if (next.length <= capturedOutputLimit) {
+    return next;
+  }
+  return next.slice(next.length - capturedOutputLimit);
+}
+
+function runCapturedProcess(command, args, options = {}, signalCoordinator) {
+  const pendingSignal = signalCoordinator && signalCoordinator.receivedSignal();
+  if (pendingSignal) {
+    return Promise.resolve({
+      code: 1,
+      signal: pendingSignal,
+      stdout: '',
+      stderr: '',
+    });
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      ...options,
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+    let releaseChild = () => {};
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout = appendCaptured(stdout, chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = appendCaptured(stderr, chunk);
+    });
+    child.once('error', (err) => {
+      releaseChild();
+      reject(err);
+    });
+    child.once('exit', (code, signal) => {
+      releaseChild();
+      resolve({ code: code === null ? 1 : code, signal, stdout, stderr });
+    });
+    if (signalCoordinator) {
+      releaseChild = signalCoordinator.track(child);
+    }
+  });
+}
+
+function createStatusRenderer(stream) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const interactive = Boolean(stream && stream.isTTY);
+  let timer;
+  let frame = 0;
+  let lineWidth = 0;
+
+  function replaceLine(text, done) {
+    if (!stream) {
+      return;
+    }
+    if (!interactive) {
+      stream.write(`${text}\n`);
+      return;
+    }
+    const padding = ' '.repeat(Math.max(lineWidth - [...text].length, 0));
+    stream.write(`\r${text}${padding}${done ? '\n' : ''}`);
+    lineWidth = done ? 0 : [...text].length;
+  }
+
+  function stopTimer() {
+    if (timer) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  }
+
+  return {
+    start(label) {
+      stopTimer();
+      if (!interactive) {
+        replaceLine(label, true);
+        return;
+      }
+      replaceLine(`${frames[frame]} ${label}`, false);
+      timer = setInterval(() => {
+        frame = (frame + 1) % frames.length;
+        replaceLine(`${frames[frame]} ${label}`, false);
+      }, 80);
+    },
+    succeed(message) {
+      stopTimer();
+      replaceLine(`✓ ${message}`, true);
+    },
+    fail(message) {
+      stopTimer();
+      replaceLine(`✗ ${message}`, true);
+    },
+    stop() {
+      stopTimer();
+    },
+  };
+}
+
+function validateHandoffPlan(plan) {
+  if (!plan || plan.version !== 1) {
+    throw new Error('invalid npm update handoff plan version');
+  }
+  if (!Array.isArray(plan.command) || plan.command.length === 0 ||
+      plan.command.some((value) => typeof value !== 'string' || value.length === 0)) {
+    throw new Error('invalid npm update command');
+  }
+  if (!plan.latest_version || !plan.executable) {
+    throw new Error('incomplete npm update handoff plan');
+  }
+}
+
+function validateHandoffOwnership(ownership) {
+  if (!ownership || ownership.version !== 1) {
+    throw new Error('invalid npm update handoff ownership version');
+  }
+  const lockPath = String(ownership.lock_path || '').trim();
+  const lockToken = String(ownership.lock_token || '').trim();
+  if (Boolean(lockPath) !== Boolean(lockToken)) {
+    throw new Error('incomplete npm update lock ownership');
+  }
+}
+
+function normalizeVersion(value) {
+  return String(value || '').trim().replace(/^v/i, '');
+}
+
+async function defaultRunInstall(plan, signalCoordinator) {
+  const executable = plan.command[0];
+  const args = plan.command.slice(1);
+  if (process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(executable)) {
+    const commandLine = String(plan.command_line || '').trim();
+    if (!commandLine) {
+      throw new Error('missing Windows npm command line');
+    }
+    return runCapturedProcess(
+      process.env.ComSpec || 'cmd.exe',
+      ['/d', '/s', '/c', commandLine],
+      { env: process.env },
+      signalCoordinator,
+    );
+  }
+  return runCapturedProcess(executable, args, { env: process.env }, signalCoordinator);
+}
+
+async function defaultVerifyVersion(executable, signalCoordinator) {
+  const result = await runCapturedProcess(
+    executable,
+    ['version', '--format', 'json'],
+    { env: process.env },
+    signalCoordinator,
+  );
+  if (result.signal || result.code !== 0) {
+    const detail = String(result.stderr || result.stdout || '').trim();
+    throw new Error(`updated Caelis did not start${detail ? `: ${detail}` : ''}`);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch (err) {
+    throw new Error(`updated Caelis returned invalid version output: ${err.message}`);
+  }
+  return payload.version;
+}
+
+function installFailure(result) {
+  if (result.signal) {
+    return new Error(`npm install terminated by signal ${result.signal}`);
+  }
+  const detail = String(result.stderr || result.stdout || '').trim();
+  return new Error(
+    `npm install exited with code ${result.code}${detail ? `\n${detail}` : ''}`,
+  );
+}
+
+function removeOwnedLock(lockPath, lockToken) {
+  if (!lockPath || !lockToken) {
+    return;
+  }
+  let current;
+  try {
+    current = fs.readFileSync(lockPath, 'utf8').trim();
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return;
+    }
+    throw err;
+  }
+  if (current !== String(lockToken).trim()) {
+    return;
+  }
+  fs.rmSync(lockPath, { force: true });
+}
+
+async function executeHandoffPlan(plan, options = {}) {
+  const stderr = options.stderr || process.stderr;
+  const stdout = options.stdout || process.stdout;
+  const status = options.status || createStatusRenderer(stderr);
+  const signalCoordinator = options.signalCoordinator;
+  const runInstall = options.runInstall ||
+    ((handoffPlan) => defaultRunInstall(handoffPlan, signalCoordinator));
+  const verifyVersion = options.verifyVersion ||
+    ((executable) => defaultVerifyVersion(executable, signalCoordinator));
+  let phase = 'install';
+
+  try {
+    validateHandoffPlan(plan);
+    status.start('Installing update with npm…');
+    const result = await runInstall(plan);
+    if (result.signal || result.code !== 0) {
+      throw installFailure(result);
+    }
+    status.succeed('npm install completed');
+
+    phase = 'verify';
+    status.start('Verifying updated Caelis…');
+    const installedVersion = await verifyVersion(plan.executable);
+    if (normalizeVersion(installedVersion) !== normalizeVersion(plan.latest_version)) {
+      throw new Error(
+        `expected ${plan.latest_version}, found ${installedVersion || 'unknown'}`,
+      );
+    }
+    status.succeed(`Verified Caelis ${plan.latest_version}`);
+    stdout.write(
+      // Keep this completion contract aligned with formatUpdateResult in
+      // internal/cli/update.go; Go is silent while a handoff is active.
+      `Caelis ${plan.latest_version} is ready ` +
+      `(updated from ${plan.current_version || 'unknown'} via npm).\n`,
+    );
+    return 0;
+  } catch (err) {
+    status.fail(phase === 'install' ? 'npm install failed' : 'Version verification failed');
+    throw err;
+  } finally {
+    status.stop();
+  }
+}
+
+function reserveHandoffDirectory(platform, options = {}) {
+  if (platform !== 'win32') {
+    return '';
+  }
+  const tmpdir = options.tmpdir || os.tmpdir;
+  const randomUUID = options.randomUUID || crypto.randomUUID;
+  return path.join(tmpdir(), `caelis-npm-update-${randomUUID()}`);
+}
+
+function readHandoffJSON(filePath, label) {
+  let data;
+  try {
+    data = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(`cannot read ${label}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(data);
+  } catch (err) {
+    throw new Error(`invalid ${label}: ${err.message}`);
+  }
+}
+
+async function completeHandoffLifecycle(handoffDir, childResult, options = {}) {
+  if (!handoffDir || !fs.existsSync(handoffDir)) {
+    return childResult;
+  }
+  const executePlan = options.executePlan ||
+    ((plan) => executeHandoffPlan(plan, {
+      signalCoordinator: options.signalCoordinator,
+    }));
+  const removeLock = options.removeLock || removeOwnedLock;
+  const ownershipPath = path.join(handoffDir, handoffOwnershipName);
+  const planPath = path.join(handoffDir, handoffPlanName);
+  let ownership;
+
+  try {
+    if (fs.existsSync(ownershipPath)) {
+      const candidate = readHandoffJSON(ownershipPath, 'npm update handoff ownership');
+      validateHandoffOwnership(candidate);
+      ownership = candidate;
+    }
+    const planExists = fs.existsSync(planPath);
+    if (!planExists) {
+      if (ownership && !childResult.signal && childResult.code === 0) {
+        throw new Error('npm update handoff plan was not published');
+      }
+      return childResult;
+    }
+    if (!ownership) {
+      throw new Error('npm update handoff ownership was not published');
+    }
+    if (childResult.signal || childResult.code !== 0) {
+      return childResult;
+    }
+    const plan = readHandoffJSON(planPath, 'npm update handoff plan');
+    const code = await executePlan(plan);
+    return { code, signal: null };
+  } finally {
+    try {
+      if (ownership) {
+        removeLock(ownership.lock_path, ownership.lock_token);
+      }
+    } finally {
+      fs.rmSync(handoffDir, { recursive: true, force: true });
+    }
+  }
+}
+
+async function completeHandoff(handoffDir, childResult, options = {}) {
+  try {
+    return await completeHandoffLifecycle(handoffDir, childResult, options);
+  } catch (err) {
+    if (err instanceof UpdateHandoffError) {
+      throw err;
+    }
+    throw new UpdateHandoffError(err.message, { cause: err });
+  }
+}
+
+module.exports = {
+  UpdateHandoffError,
+  completeHandoff,
+  createStatusRenderer,
+  executeHandoffPlan,
+  handoffEnvironment,
+  handoffOwnershipName,
+  handoffPlanName,
+  normalizeVersion,
+  removeOwnedLock,
+  reserveHandoffDirectory,
+  validateHandoffPlan,
+  validateHandoffOwnership,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelis/caelis",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "caelis CLI distributed via npm",
   "license": "Apache-2.0",
   "repository": {
@@ -16,6 +16,7 @@
   },
   "files": [
     "bin/caelis.js",
+    "lib/update-handoff.js",
     "README.md",
     "LICENSE"
   ],
@@ -29,18 +30,19 @@
     "arm64"
   ],
   "scripts": {
+    "test": "node --test ./test/*.test.js",
     "prepare": "node ./scripts/prepare.mjs",
     "set-version": "node ./scripts/set-version.mjs",
     "stage-release": "node ./scripts/stage-release.mjs",
     "publish-release": "node ./scripts/publish-release.mjs"
   },
   "optionalDependencies": {
-    "@caelis/caelis-darwin-arm64": "0.28.0",
-    "@caelis/caelis-darwin-x64": "0.28.0",
-    "@caelis/caelis-linux-arm64": "0.28.0",
-    "@caelis/caelis-linux-x64": "0.28.0",
-    "@caelis/caelis-windows-arm64": "0.28.0",
-    "@caelis/caelis-windows-x64": "0.28.0"
+    "@caelis/caelis-darwin-arm64": "0.30.0",
+    "@caelis/caelis-darwin-x64": "0.30.0",
+    "@caelis/caelis-linux-arm64": "0.30.0",
+    "@caelis/caelis-linux-x64": "0.30.0",
+    "@caelis/caelis-windows-arm64": "0.30.0",
+    "@caelis/caelis-windows-x64": "0.30.0"
   },
   "publishConfig": {
     "access": "public",