neoagent 2.3.1-beta.0 → 2.3.1-beta.100

package/lib/manager.js

@@ -18,6 +18,7 @@ const {
   LOG_DIR,
   ENV_FILE,
   PID_FILE,
+  getDefaultVmBaseImageUrl,
   ensureRuntimeDirs,
   migrateLegacyRuntime
 } = require('../runtime/paths');
@@ -118,28 +119,45 @@ function readEnvFileRaw() {
   return fs.readFileSync(ENV_FILE, 'utf8');
 }
 
+function sanitizeEnvKey(key) {
+  return String(key).replace(/[\r\n]/g, '');
+}
+
+function sanitizeEnvValue(value) {
+  return String(value).replace(/[\r\n]/g, '');
+}
+
+function validateEnvKey(key) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env key "${key}". Keys must be uppercase letters, digits, and underscores (e.g. PORT, ANTHROPIC_API_KEY).`);
+  }
+}
+
 function upsertEnvValue(key, value) {
+  const safeKey = sanitizeEnvKey(key);
+  const safeValue = sanitizeEnvValue(value);
   const raw = readEnvFileRaw();
   const lines = raw ? raw.split('\n') : [];
   let replaced = false;
 
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith(`${key}=`)) {
-      lines[i] = `${key}=${value}`;
+    if (lines[i].startsWith(`${safeKey}=`)) {
+      lines[i] = `${safeKey}=${safeValue}`;
       replaced = true;
       break;
     }
   }
 
-  if (!replaced) lines.push(`${key}=${value}`);
+  if (!replaced) lines.push(`${safeKey}=${safeValue}`);
   const output = lines.filter((_, idx, arr) => idx !== arr.length - 1 || arr[idx] !== '').join('\n') + '\n';
   fs.writeFileSync(ENV_FILE, output, { mode: 0o600 });
 }
 
 function removeEnvValue(key) {
+  const safeKey = sanitizeEnvKey(key);
   const raw = readEnvFileRaw();
   if (!raw) return false;
-  const lines = raw.split('\n').filter((line) => !line.startsWith(`${key}=`));
+  const lines = raw.split('\n').filter((line) => !line.startsWith(`${safeKey}=`));
   const output = lines.filter((_, idx, arr) => idx !== arr.length - 1 || arr[idx] !== '').join('\n') + '\n';
   fs.writeFileSync(ENV_FILE, output, { mode: 0o600 });
   return true;
@@ -287,6 +305,38 @@ function ensureLogDir() {
   ensureRuntimeDirs();
 }
 
+function pruneOldRuntimeBackups(backupsDir, keepLatest = 3) {
+  if (!fs.existsSync(backupsDir) || keepLatest < 0) return;
+
+  const backupDirs = fs
+    .readdirSync(backupsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('pre-update-'))
+    .map((entry) => {
+      const fullPath = path.join(backupsDir, entry.name);
+      let mtimeMs = 0;
+      try {
+        mtimeMs = fs.statSync(fullPath).mtimeMs;
+      } catch {
+        // Skip entries that disappear or cannot be statted.
+        return null;
+      }
+      return { name: entry.name, fullPath, mtimeMs };
+    })
+    .filter(Boolean)
+    .sort((a, b) => {
+      if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+      return b.name.localeCompare(a.name);
+    });
+
+  for (const backup of backupDirs.slice(keepLatest)) {
+    try {
+      fs.rmSync(backup.fullPath, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+}
+
 function backupRuntimeData() {
   const backupsDir = path.join(RUNTIME_HOME, 'backups');
   fs.mkdirSync(backupsDir, { recursive: true });
@@ -296,6 +346,7 @@ function backupRuntimeData() {
 
   if (fs.existsSync(ENV_FILE)) fs.copyFileSync(ENV_FILE, path.join(target, '.env'));
   if (fs.existsSync(DATA_DIR)) fs.cpSync(DATA_DIR, path.join(target, 'data'), { recursive: true, force: false, errorOnExist: false });
+  pruneOldRuntimeBackups(backupsDir, 3);
 }
 
 function killByPort(port) {
@@ -347,15 +398,19 @@ function listNeoAgentServerProcesses() {
       };
     })
     .filter(Boolean)
-    .filter((entry) =>
-      entry.pid !== process.pid &&
-      /(^|\s)node(\s|$)/.test(entry.command) &&
-      (
-        appIndexPattern.test(String(entry.command || '').replace(/\\/g, '/')) ||
-        genericNeoAgentPattern.test(String(entry.command || '').replace(/\\/g, '/')) ||
-        repoNamePattern.test(String(entry.command || ''))
-      )
-    );
+    .filter((entry) => {
+      if (entry.pid === process.pid) return false;
+      const cmd = String(entry.command || '');
+      const cmdNormalized = cmd.replace(/\\/g, '/');
+      const executablePart = cmd.split(/\s+/)[0] || '';
+      const executableBase = path.basename(executablePart);
+      const isNode = /^node\d*$/.test(executableBase) || /(^|\s)node\d*(\s|$)/.test(cmd);
+      return isNode && (
+        appIndexPattern.test(cmdNormalized) ||
+        genericNeoAgentPattern.test(cmdNormalized) ||
+        repoNamePattern.test(cmd)
+      );
+    });
 }
 
 function killNeoAgentServerProcesses() {
@@ -425,18 +480,24 @@ async function cmdSetup() {
   ensureRuntimeDirs();
 
   const current = Object.fromEntries(parseEnv(readEnvFileRaw()).entries());
+  const defaultVmBaseImageUrl = getDefaultVmBaseImageUrl();
 
   logInfo('Press Enter to keep the current value shown in brackets.');
 
   heading('Core');
-  const port = await ask('Server port', current.PORT || '3333');
+  const portRaw = await ask('Server port', current.PORT || '3333');
+  const portNum = Number(portRaw);
+  if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) {
+    throw new Error(`Invalid port "${portRaw}". Must be an integer between 1 and 65535.`);
+  }
+  const port = String(portNum);
   const publicUrl = await ask('Public base URL', current.PUBLIC_URL || '');
   const secureCookiesDefault = current.SECURE_COOKIES ||
     (String(publicUrl || '').trim().startsWith('https://') ? 'true' : 'false');
   const secureCookies = await ask('Secure cookies (true/false)', secureCookiesDefault);
   const trustProxyDefault = current.TRUST_PROXY || secureCookiesDefault;
   const trustProxy = await ask('Trust reverse proxy headers (true/false)', trustProxyDefault);
-  const sessionSecret = await askSecret('Session secret', current.SESSION_SECRET || randomSecret());
+  const sessionSecret = current.SESSION_SECRET || randomSecret();
   const deploymentMode = await ask(
     'Deployment mode (self_hosted/managed)',
     current.NEOAGENT_DEPLOYMENT_MODE || 'self_hosted'
@@ -446,6 +507,11 @@ async function cmdSetup() {
     current.NEOAGENT_RELEASE_CHANNEL || 'stable'
   );
   const origins = await ask('Allowed CORS origins', current.ALLOWED_ORIGINS || '');
+  const deploymentProfile = current.NEOAGENT_PROFILE || 'prod';
+  const vmBaseImageUrl = current.NEOAGENT_VM_BASE_IMAGE_URL || defaultVmBaseImageUrl;
+  const vmMemoryMb = current.NEOAGENT_VM_MEMORY_MB || '4096';
+  const vmCpus = current.NEOAGENT_VM_CPUS || '2';
+  const vmGuestToken = current.NEOAGENT_VM_GUEST_TOKEN || randomSecret();
 
   heading('AI Providers');
   const anthropic = await askSecret('Anthropic API key', current.ANTHROPIC_API_KEY || '');
@@ -542,6 +608,19 @@ async function cmdSetup() {
   const normalizedDeploymentMode = parseDeploymentMode(deploymentMode);
   const normalizedReleaseChannel = parseReleaseChannel(releaseChannel) || 'stable';
 
+  const githubOauthClientId = await askSecret(
+    'GitHub OAuth client ID',
+    current.GITHUB_OAUTH_CLIENT_ID || ''
+  );
+  const githubOauthClientSecret = await askSecret(
+    'GitHub OAuth client secret',
+    current.GITHUB_OAUTH_CLIENT_SECRET || ''
+  );
+  const githubOauthRedirectUri = await ask(
+    'GitHub OAuth redirect URI',
+    current.GITHUB_OAUTH_REDIRECT_URI || ''
+  );
+
   const lines = [
     `NODE_ENV=production`,
     `PORT=${port}`,
@@ -549,8 +628,13 @@ async function cmdSetup() {
     `SECURE_COOKIES=${normalizedSecureCookies}`,
     `TRUST_PROXY=${normalizedTrustProxy}`,
     `SESSION_SECRET=${sessionSecret}`,
+    `NEOAGENT_PROFILE=${deploymentProfile}`,
     `NEOAGENT_DEPLOYMENT_MODE=${normalizedDeploymentMode}`,
     `NEOAGENT_RELEASE_CHANNEL=${normalizedReleaseChannel}`,
+    `NEOAGENT_VM_BASE_IMAGE_URL=${vmBaseImageUrl}`,
+    `NEOAGENT_VM_MEMORY_MB=${vmMemoryMb}`,
+    `NEOAGENT_VM_CPUS=${vmCpus}`,
+    `NEOAGENT_VM_GUEST_TOKEN=${vmGuestToken}`,
     anthropic ? `ANTHROPIC_API_KEY=${anthropic}` : '',
     anthropicBaseUrl ? `ANTHROPIC_BASE_URL=${anthropicBaseUrl}` : '',
     openai ? `OPENAI_API_KEY=${openai}` : '',
@@ -576,6 +660,9 @@ async function cmdSetup() {
     figmaOauthClientId ? `FIGMA_OAUTH_CLIENT_ID=${figmaOauthClientId}` : '',
     figmaOauthClientSecret ? `FIGMA_OAUTH_CLIENT_SECRET=${figmaOauthClientSecret}` : '',
     figmaOauthRedirectUri ? `FIGMA_OAUTH_REDIRECT_URI=${figmaOauthRedirectUri}` : '',
+    githubOauthClientId ? `GITHUB_OAUTH_CLIENT_ID=${githubOauthClientId}` : '',
+    githubOauthClientSecret ? `GITHUB_OAUTH_CLIENT_SECRET=${githubOauthClientSecret}` : '',
+    githubOauthRedirectUri ? `GITHUB_OAUTH_REDIRECT_URI=${githubOauthRedirectUri}` : '',
     deepgramApiKey ? `DEEPGRAM_API_KEY=${deepgramApiKey}` : '',
     deepgramBaseUrl ? `DEEPGRAM_BASE_URL=${deepgramBaseUrl}` : '',
     deepgramModel ? `DEEPGRAM_MODEL=${deepgramModel}` : '',
@@ -674,6 +761,141 @@ async function cmdMigrate(args = []) {
   });
 }
 
+async function pollDeviceCode({ pollUrl, pollBody, pollHeaders = {}, intervalMs, timeoutMs, onToken }) {
+  const start = Date.now();
+  let currentInterval = intervalMs;
+  while (Date.now() - start < timeoutMs) {
+    await new Promise((r) => setTimeout(r, currentInterval));
+    const res = await fetch(pollUrl, {
+      method: 'POST',
+      headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', ...pollHeaders },
+      body: JSON.stringify(pollBody()),
+    });
+    if (res.status === 403 || res.status === 404) continue;
+    if (!res.ok) {
+      const text = await res.text().catch(() => 'Unknown error');
+      throw new Error(`Token poll failed: HTTP ${res.status} — ${text}`);
+    }
+    const data = await res.json();
+    const done = await onToken(data);
+    if (done) return;
+    if (data.error === 'authorization_pending') continue;
+    if (data.error === 'slow_down') { currentInterval += 5000; continue; }
+    if (data.error) throw new Error(`Authentication failed: ${data.error_description || data.error}`);
+  }
+  throw new Error('Authentication timed out after 15 minutes.');
+}
+
+async function cmdLogin(args = []) {
+  const provider = args[0];
+  if (provider !== 'github-copilot' && provider !== 'openai-codex') {
+    throw new Error(`Unsupported login provider: ${provider || 'none'}. Available: github-copilot, openai-codex`);
+  }
+
+  if (provider === 'github-copilot') {
+    heading('GitHub Copilot Login');
+    const clientId = '01ab8ac9400c4e429b23';
+    logInfo('Requesting device code from GitHub...');
+
+    const reqRes = await fetch('https://github.com/login/device/code', {
+      method: 'POST',
+      headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_id: clientId, scope: 'user:email' })
+    });
+    if (!reqRes.ok) throw new Error(`Failed to request device code: HTTP ${reqRes.status}`);
+
+    const { device_code, user_code, verification_uri, interval } = await reqRes.json();
+    console.log(`\n  ${COLORS.cyan}Please visit:${COLORS.reset} ${verification_uri}`);
+    console.log(`  ${COLORS.cyan}Enter code:${COLORS.reset}   ${COLORS.bold}${user_code}${COLORS.reset}\n`);
+    logInfo('Waiting for authorization (timeout in 15m)...');
+
+    await pollDeviceCode({
+      pollUrl: 'https://github.com/login/oauth/access_token',
+      pollBody: () => ({ client_id: clientId, device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+      intervalMs: (interval || 5) * 1000,
+      timeoutMs: 15 * 60 * 1000,
+      onToken: async (data) => {
+        if (!data.access_token) return false;
+        upsertEnvValue('GITHUB_COPILOT_ACCESS_TOKEN', data.access_token);
+        logOk('Saved GitHub Copilot access token to .env');
+        logInfo('Restarting NeoAgent to apply credentials...');
+        cmdRestart();
+        return true;
+      },
+    });
+    return;
+  } else if (provider === 'openai-codex') {
+    heading('OpenAI Codex Login');
+    const clientId = 'app_EMoamEEZ73f0CkXaXp7hrann';
+    logInfo('Requesting device code from OpenAI...');
+
+    const reqRes = await fetch('https://auth.openai.com/api/accounts/deviceauth/usercode', {
+      method: 'POST',
+      headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_id: clientId, scope: 'openid profile email offline_access model.request model.read model.create' })
+    });
+
+    if (!reqRes.ok) {
+      throw new Error(`Failed to request device code: HTTP ${reqRes.status}`);
+    }
+
+    const data = await reqRes.json();
+    const { device_auth_id, interval } = data;
+    const user_code = data.user_code || data.usercode;
+    const verification_uri = 'https://auth.openai.com/codex/device';
+
+    console.log(`\n  ${COLORS.cyan}Please visit:${COLORS.reset} ${verification_uri}`);
+    console.log(`  ${COLORS.cyan}Enter code:${COLORS.reset}   ${COLORS.bold}${user_code}${COLORS.reset}\n`);
+    logInfo('Waiting for authorization (timeout in 15m)...');
+
+    let authorizationCode = null;
+    let codeVerifier = null;
+
+    await pollDeviceCode({
+      pollUrl: 'https://auth.openai.com/api/accounts/deviceauth/token',
+      pollBody: () => ({ device_auth_id, user_code }),
+      intervalMs: (interval || 5) * 1000,
+      timeoutMs: 15 * 60 * 1000,
+      onToken: async (data) => {
+        if (!data.authorization_code || !data.code_verifier) return false;
+        authorizationCode = data.authorization_code;
+        codeVerifier = data.code_verifier;
+        return true;
+      },
+    });
+
+    logInfo('Exchanging authorization code for access token...');
+    const exchangeRes = await fetch('https://auth.openai.com/oauth/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: authorizationCode,
+        redirect_uri: 'https://auth.openai.com/deviceauth/callback',
+        client_id: clientId,
+        code_verifier: codeVerifier,
+      }),
+    });
+
+    if (!exchangeRes.ok) {
+      const errorText = await exchangeRes.text().catch(() => 'Unknown error');
+      throw new Error(`OpenAI token exchange failed: HTTP ${exchangeRes.status} — ${errorText}`);
+    }
+
+    const exchangeData = await exchangeRes.json();
+    if (!exchangeData.access_token) {
+      throw new Error('OpenAI token exchange succeeded but did not return an access token.');
+    }
+    upsertEnvValue('OPENAI_CODEX_ACCESS_TOKEN', exchangeData.access_token);
+    if (exchangeData.refresh_token) {
+      upsertEnvValue('OPENAI_CODEX_REFRESH_TOKEN', exchangeData.refresh_token);
+    }
+    logOk('Saved OpenAI Codex tokens to .env');
+    logInfo('Restarting NeoAgent to apply credentials...');
+    cmdRestart();
+  }
+}
+
 function installDependencies() {
   heading('Dependencies');
   runOrThrow('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], {
@@ -770,6 +992,109 @@ function startFallback() {
   logOk(`Started detached process (pid ${child.pid})`);
 }
 
+async function ensureQemuInstalled() {
+  heading('Ensure QEMU Installed');
+  const platform = detectPlatform();
+  
+  const hasSystem = commandExists('qemu-system-x86_64') || commandExists('qemu-system-aarch64');
+  const hasImg = commandExists('qemu-img');
+
+  if (hasSystem && hasImg) {
+    logOk('QEMU components are already installed');
+    return;
+  }
+
+  logInfo('QEMU components not found. Attempting to install...');
+
+  if (platform === 'macos') {
+    if (!commandExists('brew')) {
+      throw new Error('Homebrew is required to install QEMU on macOS. Please install it first: https://brew.sh/');
+    }
+    logInfo('Running "brew install qemu"...');
+    runOrThrow('brew', ['install', 'qemu']);
+  } else if (platform === 'linux') {
+    const isArm = process.arch === 'arm64' || process.arch === 'aarch64';
+    if (commandExists('apt-get')) {
+      const pkgs = ['qemu-utils'];
+      if (isArm) {
+        pkgs.push('qemu-system-arm');
+      } else {
+        pkgs.push('qemu-system-x86');
+      }
+      logInfo(`Running "sudo apt-get update && sudo apt-get install -y ${pkgs.join(' ')}"...`);
+      runOrThrow('sudo', ['apt-get', 'update']);
+      runOrThrow('sudo', ['apt-get', 'install', '-y', ...pkgs]);
+    } else if (commandExists('dnf')) {
+      logInfo('Running "sudo dnf install -y qemu-kvm qemu-img"...');
+      runOrThrow('sudo', ['dnf', 'install', '-y', 'qemu-kvm', 'qemu-img']);
+    } else if (commandExists('yum')) {
+      logInfo('Running "sudo yum install -y qemu-kvm qemu-img"...');
+      runOrThrow('sudo', ['yum', 'install', '-y', 'qemu-kvm', 'qemu-img']);
+    } else {
+      throw new Error('Unsupported Linux distribution. Please install qemu-system and qemu-utils manually.');
+    }
+  } else {
+    throw new Error('Unsupported platform for automatic QEMU installation. Please install QEMU manually.');
+  }
+
+  const verifiedSystem = commandExists('qemu-system-x86_64') || commandExists('qemu-system-aarch64');
+  const verifiedImg = commandExists('qemu-img');
+
+  if (verifiedSystem && verifiedImg) {
+    logOk('QEMU installed successfully');
+  } else {
+    throw new Error('QEMU installation failed or components not found in PATH after install.');
+  }
+}
+
+function ensureYtDlpInstalled() {
+  heading('Ensure yt-dlp Installed');
+  if (commandExists('yt-dlp')) {
+    const ver = runQuiet('yt-dlp', ['--version']);
+    logOk(`yt-dlp ${ver.status === 0 ? ver.stdout.trim() : '(version unknown)'}`);
+    return;
+  }
+
+  logInfo('yt-dlp not found. Attempting to install...');
+  const platform = detectPlatform();
+
+  if (platform === 'macos') {
+    if (!commandExists('brew')) {
+      logWarn('Homebrew not found — skipping yt-dlp install. Install manually: brew install yt-dlp');
+      return;
+    }
+    try {
+      runOrThrow('brew', ['install', 'yt-dlp']);
+      logOk('yt-dlp installed via Homebrew');
+    } catch {
+      logWarn('yt-dlp install failed. Install manually: brew install yt-dlp');
+    }
+    return;
+  }
+
+  if (platform === 'linux') {
+    if (commandExists('pipx')) {
+      try {
+        runOrThrow('pipx', ['install', 'yt-dlp']);
+        logOk('yt-dlp installed via pipx');
+        return;
+      } catch {
+        // fall through to pip3
+      }
+    }
+    if (commandExists('pip3')) {
+      try {
+        runOrThrow('pip3', ['install', '--user', 'yt-dlp']);
+        logOk('yt-dlp installed via pip3');
+        return;
+      } catch {
+        // fall through to warn
+      }
+    }
+    logWarn('Could not install yt-dlp automatically. Install manually: pipx install yt-dlp');
+  }
+}
+
 async function cmdInstall() {
   heading(`Install ${APP_NAME}`);
   if (!fs.existsSync(ENV_FILE)) {
@@ -778,6 +1103,8 @@ async function cmdInstall() {
   }
 
   installDependencies();
+  await ensureQemuInstalled();
+  ensureYtDlpInstalled();
   buildBundledWebClientIfPossible({ required: true });
 
   const platform = detectPlatform();
@@ -839,7 +1166,7 @@ function cmdStop() {
           logOk(`Stopped pid ${pid}`);
           stopped = true;
         } catch {
-          logWarn(`pid ${pid} not running`);
+          logWarn(`pid ${pid} was not running (stale PID file)`);
         }
       }
       fs.rmSync(pidPath, { force: true });
@@ -867,6 +1194,11 @@ function cmdRestart() {
   cmdStart();
 }
 
+async function cmdRebuildWeb() {
+  heading(`Rebuild Flutter Web Client`);
+  buildBundledWebClientIfPossible();
+}
+
 function cmdUninstall() {
   heading(`Uninstall ${APP_NAME}`);
   const platform = detectPlatform();
@@ -895,22 +1227,52 @@ async function cmdStatus() {
   const port = loadEnvPort();
   const running = await isPortOpen(port);
   const releaseChannel = currentReleaseChannel();
+  const platform = detectPlatform();
 
   if (running) {
-    logOk(`running on http://localhost:${port}`);
+    logOk(`server   http://localhost:${port}`);
+  } else {
+    logWarn(`server   not reachable on port ${port}`);
+  }
+
+  if (platform === 'macos' && fs.existsSync(PLIST_DST)) {
+    const svcRes = runQuiet('launchctl', ['list', SERVICE_LABEL]);
+    if (svcRes.status === 0 && svcRes.stdout.trim()) {
+      logOk(`service  launchd (${SERVICE_LABEL})`);
+    } else {
+      logWarn(`service  launchd unit not loaded — run: neoagent install`);
+    }
+  } else if (platform === 'linux' && fs.existsSync(SYSTEMD_UNIT)) {
+    const svcRes = runQuiet('systemctl', ['--user', 'is-active', 'neoagent']);
+    if (svcRes.status === 0 && svcRes.stdout.trim() === 'active') {
+      logOk('service  systemd (neoagent)');
+    } else {
+      logWarn('service  systemd unit not active — run: neoagent install');
+    }
+  }
+
+  if (fs.existsSync(ENV_FILE)) {
+    logOk(`config   ${ENV_FILE}`);
+  } else {
+    logWarn(`config   .env not found — run: neoagent setup`);
+  }
+
+  if (hasBundledWebClient(WEB_CLIENT_DIR)) {
+    logOk('web      bundled Flutter client present');
   } else {
-    logWarn(`not reachable on port ${port}`);
+    logWarn('web      no bundled client — run: neoagent rebuild-web');
   }
 
-  console.log(`  install root ${APP_DIR}`);
-  console.log(`  version ${currentInstalledVersionLabel()}`);
-  console.log(`  release channel ${releaseChannelSummary(releaseChannel)}`);
+  console.log('');
+  console.log(`  install  ${APP_DIR}`);
+  console.log(`  version  ${currentInstalledVersionLabel()}`);
+  console.log(`  channel  ${releaseChannelSummary(releaseChannel)}`);
 
   const processes = listNeoAgentServerProcesses();
   if (processes.length > 0) {
-    console.log(`  neoagent pids ${processes.map((proc) => proc.pid).join(', ')}`);
+    console.log(`  pids     ${processes.map((proc) => proc.pid).join(', ')}`);
     if (processes.length > 1) {
-      logWarn(`multiple NeoAgent server processes detected (${processes.length})`);
+      logWarn(`multiple NeoAgent processes detected (${processes.length})`);
     }
   }
 }
@@ -962,6 +1324,8 @@ function cmdUpdate(args = []) {
   }
   const versionBefore = currentInstalledVersionLabel();
   let versionAfter = versionBefore;
+  const githubInstallRef = releaseChannel === 'beta' ? '#beta' : '';
+  const githubInstallSpec = `git+https://github.com/NeoLabs-Systems/NeoAgent.git${githubInstallRef}`;
 
   if (fs.existsSync(path.join(APP_DIR, '.git')) && commandExists('git')) {
     const current = runQuiet('git', ['rev-parse', '--short', 'HEAD']);
@@ -970,6 +1334,7 @@ function cmdUpdate(args = []) {
     const targetBranch = resolvePreferredGitBranch(releaseChannel);
     logInfo(`Using git branch ${targetBranch} for the ${releaseChannel} channel.`);
     ensureGitBranchForReleaseChannel(targetBranch);
+    backupRuntimeData();
     runOrThrow('git', ['pull', '--rebase', '--autostash', 'origin', targetBranch]);
 
     const next = runQuiet('git', ['rev-parse', '--short', 'HEAD']);
@@ -982,17 +1347,16 @@ function cmdUpdate(args = []) {
       buildBundledWebClientIfPossible();
     }
   } else {
-    const npmTag = resolvePreferredNpmTag(releaseChannel);
-    logWarn(`No git repo detected; attempting npm global update from ${npmTag}.`);
+    logWarn(`No git repo detected; attempting npm global update from ${githubInstallSpec}.`);
     if (commandExists('npm')) {
       try {
         backupRuntimeData();
-        runOrThrow('npm', ['install', '-g', `neoagent@${npmTag}`, '--force'], {
+        runOrThrow('npm', ['install', '-g', githubInstallSpec, '--force'], {
           env: withInstallEnv()
         });
-        logOk('npm global update completed (forced reinstall)');
+        logOk('npm global update completed (forced reinstall from GitHub)');
       } catch {
-        logWarn(`npm global update failed. Run: npm install -g neoagent@${npmTag} --force`);
+        logWarn(`npm global update failed. Run: npm install -g ${githubInstallSpec} --force`);
       }
     } else {
       logWarn('npm not found. Cannot perform global update.');
@@ -1000,6 +1364,7 @@ function cmdUpdate(args = []) {
   }
 
   versionAfter = currentInstalledVersionLabel();
+  ensureYtDlpInstalled();
 
   if (!hasBundledWebClient(WEB_CLIENT_DIR)) {
     throw new Error('No bundled Flutter web client found after update.');
@@ -1011,11 +1376,16 @@ function cmdUpdate(args = []) {
 
 async function cmdEnv(args = []) {
   heading('Environment Variables');
-  let action = args[0];
+  const action = (args[0] || '').trim().toLowerCase();
 
   if (!action) {
-    const picked = await ask('Action (list/get/set/unset)', 'list');
-    action = (picked || 'list').trim().toLowerCase();
+    console.log('Usage: neoagent env <subcommand>');
+    console.log('');
+    console.log('  neoagent env list            List all variables (secrets masked)');
+    console.log('  neoagent env get KEY         Print a single variable');
+    console.log('  neoagent env set KEY VALUE   Set a variable');
+    console.log('  neoagent env unset KEY       Remove a variable');
+    return;
   }
 
   if (action === 'list') {
@@ -1040,16 +1410,17 @@ async function cmdEnv(args = []) {
   }
 
   if (action === 'set') {
-    const key = args[1] || await ask('Key', 'PORT');
-    const value = args.slice(2).join(' ') || await ask('Value', key === 'PORT' ? '3333' : '');
+    const key = args[1];
+    const value = args.slice(2).join(' ');
     if (!key || !value) throw new Error('Usage: neoagent env set <KEY> <VALUE>');
+    validateEnvKey(key);
     upsertEnvValue(key, value);
     logOk(`Set ${key} in ${ENV_FILE}`);
     return;
   }
 
   if (action === 'unset') {
-    const key = args[1] || await ask('Key', 'PORT');
+    const key = args[1];
     if (!key) throw new Error('Usage: neoagent env unset <KEY>');
     removeEnvValue(key);
     logOk(`Removed ${key} from ${ENV_FILE}`);
@@ -1059,15 +1430,55 @@ async function cmdEnv(args = []) {
   throw new Error('Usage: neoagent env [list|get|set|unset] ...');
 }
 
+function cmdVersion() {
+  console.log(currentInstalledVersionLabel());
+}
+
 function printHelp() {
-  console.log(`${APP_NAME} manager`);
-  console.log('Usage: neoagent <command>');
-  console.log('Commands: install | setup | env | channel | update | restart | start | stop | status | logs | uninstall | migrate');
-  console.log('Channel usage: neoagent channel | neoagent channel stable | neoagent channel beta');
-  console.log('Update usage: neoagent update | neoagent update stable | neoagent update beta');
-  console.log('Env usage: neoagent env list | neoagent env get PORT | neoagent env set PORT 3333 | neoagent env unset PORT');
-  console.log('Migrate usage: neoagent migrate | neoagent migrate dry-run | neoagent migrate status');
-  console.log('               neoagent migrate openclaw-only | neoagent migrate hermes-only');
+  const c = COLORS;
+  const W = 38;
+
+  function row(cmd, desc) {
+    const padded = `  neoagent ${cmd}`.padEnd(W);
+    console.log(`${padded}${c.dim}${desc}${c.reset}`);
+  }
+
+  console.log(`\n${c.bold}neoagent${c.reset}  —  manage your NeoAgent server\n`);
+  console.log(`${c.bold}Usage${c.reset}  neoagent <command> [args]\n`);
+
+  console.log(`${c.bold}Lifecycle${c.reset}`);
+  row('install',              'First-time install and service setup');
+  row('start',               'Start the server');
+  row('stop',                'Stop the server');
+  row('restart',             'Stop, then start');
+  row('status',              'Health overview (server, service, config)');
+  row('logs',                'Tail server logs');
+  row('uninstall',           'Remove the system service');
+  console.log('');
+
+  console.log(`${c.bold}Configuration${c.reset}`);
+  row('setup',               'Interactive configuration wizard');
+  row('env list',            'List all variables (secrets masked)');
+  row('env get KEY',         'Print a single variable');
+  row('env set KEY VALUE',   'Set a variable');
+  row('env unset KEY',       'Remove a variable');
+  row('channel',             'Show current release channel');
+  row('channel stable|beta', 'Switch release channel');
+  console.log('');
+
+  console.log(`${c.bold}Updates & Auth${c.reset}`);
+  row('update',              'Update to latest on current channel');
+  row('update stable|beta',  'Update and switch channel');
+  row('login github-copilot','Authenticate GitHub Copilot');
+  row('login openai-codex',  'Authenticate OpenAI Codex');
+  console.log('');
+
+  console.log(`${c.bold}Maintenance${c.reset}`);
+  row('migrate',             'Migrate from another agent installation');
+  row('migrate dry-run',     'Preview what would be migrated');
+  row('rebuild-web',         'Rebuild the bundled Flutter web client');
+  row('version',             'Print installed version');
+  console.log('');
 }
 
 async function runCLI(argv) {
@@ -1094,6 +1505,9 @@ async function runCLI(argv) {
     case 'restart':
       cmdRestart();
       break;
+    case 'rebuild-web':
+      await cmdRebuildWeb();
+      break;
     case 'start':
       cmdStart();
       break;
@@ -1112,13 +1526,21 @@ async function runCLI(argv) {
     case 'migrate':
       await cmdMigrate(argv.slice(1));
       break;
+    case 'login':
+      await cmdLogin(argv.slice(1));
+      break;
+    case 'version':
+    case '--version':
+    case '-V':
+      cmdVersion();
+      break;
     case 'help':
     case '--help':
     case '-h':
       printHelp();
       break;
     default:
-      throw new Error(`Unknown command: ${command}`);
+      throw new Error(`Unknown command: ${command}. Run "neoagent --help" for usage.`);
   }
 }