@rudderhq/cli 0.1.0-canary.2 → 0.1.0-canary.4

package/dist/index.js

@@ -1109,7 +1109,7 @@ var init_secret = __esm({
 
 // ../packages/shared/src/validators/agent.ts
 import { z as z10 } from "zod";
-var agentPermissionsSchema, agentInstructionsBundleModeSchema, updateAgentInstructionsBundleSchema, upsertAgentInstructionsFileSchema, agentRuntimeConfigSchema, optionalAgentNameSchema, createAgentSchema, createAgentHireSchema, updateAgentSchema, updateAgentInstructionsPathSchema, createAgentKeySchema, wakeAgentSchema, resetAgentSessionSchema, testAgentRuntimeEnvironmentSchema, updateAgentPermissionsSchema;
+var agentPermissionsSchema, agentInstructionsBundleModeSchema, updateAgentInstructionsBundleSchema, upsertAgentInstructionsFileSchema, agentRuntimeConfigSchema, optionalAgentNameSchema, uploadedAgentIconSchema, customAgentIconSchema, agentIconSchema, createAgentSchema, createAgentHireSchema, updateAgentSchema, updateAgentInstructionsPathSchema, createAgentKeySchema, wakeAgentSchema, resetAgentSessionSchema, testAgentRuntimeEnvironmentSchema, updateAgentPermissionsSchema;
 var init_agent = __esm({
   "../packages/shared/src/validators/agent.ts"() {
     "use strict";
@@ -1150,11 +1150,28 @@ var init_agent = __esm({
       },
       z10.string().trim().min(1).optional()
     );
+    uploadedAgentIconSchema = z10.string().regex(
+      /^asset:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+      "Invalid uploaded avatar reference"
+    );
+    customAgentIconSchema = z10.string().trim().min(1).max(24).refine((value) => !value.toLowerCase().startsWith("asset:"), "Invalid uploaded avatar reference").refine((value) => !/[<>\u0000-\u001f\u007f]/u.test(value), "Icon cannot contain markup or control characters");
+    agentIconSchema = z10.preprocess(
+      (value) => {
+        if (typeof value !== "string") return value;
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+      },
+      z10.union([
+        z10.enum(AGENT_ICON_NAMES),
+        uploadedAgentIconSchema,
+        customAgentIconSchema
+      ]).nullable()
+    );
     createAgentSchema = z10.object({
       name: optionalAgentNameSchema,
       role: z10.enum(AGENT_ROLES).optional().default("general"),
       title: z10.string().optional().nullable(),
-      icon: z10.enum(AGENT_ICON_NAMES).optional().nullable(),
+      icon: agentIconSchema.optional(),
       reportsTo: z10.string().uuid().optional().nullable(),
       capabilities: z10.string().optional().nullable(),
       desiredSkills: z10.array(z10.string().min(1)).optional(),
@@ -7866,6 +7883,9 @@ function isTransientBinaryPath(candidatePath) {
   return normalized.includes("/_npx/");
 }
 function hasGlobalInstalledPackage(packageName, execFileSyncImpl = execFileSync) {
+  return getGlobalInstalledPackageVersion(packageName, execFileSyncImpl) !== null;
+}
+function getGlobalInstalledPackageVersion(packageName, execFileSyncImpl = execFileSync) {
   try {
     const output = execFileSyncImpl(
       process.platform === "win32" ? "npm.cmd" : "npm",
@@ -7876,9 +7896,9 @@ function hasGlobalInstalledPackage(packageName, execFileSyncImpl = execFileSync)
       }
     );
     const parsed = JSON.parse(output);
-    return Boolean(parsed.dependencies?.[packageName]?.version);
+    return parsed.dependencies?.[packageName]?.version ?? null;
   } catch {
-    return false;
+    return null;
   }
 }
 function hasPersistentBinaryOnPath(execFileSyncImpl = execFileSync) {
@@ -9878,21 +9898,25 @@ ${err instanceof Error ? err.message : String(err)}`
 
 // src/commands/start.ts
 init_install();
-import { spawnSync as spawnSync2 } from "node:child_process";
+import { spawn, spawnSync as spawnSync2 } from "node:child_process";
 import { createHash as createHash3 } from "node:crypto";
-import { createWriteStream, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync } from "node:fs";
-import { chmod, mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { constants as fsConstants, createWriteStream, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync } from "node:fs";
+import { access, chmod, copyFile, cp, mkdtemp, mkdir, readFile as readFile3, readdir as readdir2, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 import path9 from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import * as p13 from "@clack/prompts";
 import pc8 from "picocolors";
 var DEFAULT_DESKTOP_RELEASE_REPO = "Undertone0809/rudder";
+var DESKTOP_UPDATE_QUIT_ARG = "--rudder-update-quit";
 var STABLE_SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
 var CANARY_SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+-canary\.[0-9]+$/;
 var CLI_REGISTRY_LATEST_URL = "https://registry.npmjs.org/@rudderhq%2fcli/latest";
+var DESKTOP_APP_NAME = "Rudder";
+var DESKTOP_METADATA_FILE = ".rudder-desktop-install.json";
 function resolveCurrentCliVersion(env = process.env) {
   const envPackageName = env.npm_package_name?.trim();
   const envPackageVersion = env.npm_package_version?.trim();
@@ -9916,6 +9940,9 @@ function resolveCliInstallSpec(version, env = process.env) {
   if (version && version !== "latest") return `${CLI_NPM_PACKAGE_NAME}@${version}`;
   return resolvePersistentCliInstallSpec(env);
 }
+function isPersistentCliVersionCurrent(version, installedVersion) {
+  return Boolean(version && version !== "latest" && installedVersion === version);
+}
 function compareStableSemver(a, b) {
   const aMatch = a.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)$/);
   const bMatch = b.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)$/);
@@ -9955,18 +9982,59 @@ function resolveDesktopReleaseTag(version) {
   if (STABLE_SEMVER_RE.test(version)) return `v${version}`;
   if (CANARY_SEMVER_RE.test(version)) return `canary/v${version}`;
   throw new Error(
-    `Desktop installer lookup requires a release version like 0.1.0 or 0.1.0-canary.0. Received ${version}.`
+    `Desktop release lookup requires a release version like 0.1.0 or 0.1.0-canary.0. Received ${version}.`
   );
 }
 function resolveDesktopAssetTarget(platform = process.platform, arch = process.arch) {
-  const normalizedArch = arch === "x64" || arch === "arm64" ? arch : null;
-  if (!normalizedArch) {
-    throw new Error(`Rudder Desktop does not publish installers for ${platform}/${arch}.`);
+  if (platform === "darwin") {
+    if (arch !== "x64" && arch !== "arm64") {
+      throw new Error(`Rudder Desktop does not publish portable assets for ${platform}/${arch}.`);
+    }
+    return { platform: "macos", arch, extension: ".zip" };
   }
-  if (platform === "darwin") return { platform: "macos", arch: normalizedArch, extension: ".dmg" };
-  if (platform === "win32") return { platform: "windows", arch: normalizedArch, extension: ".exe" };
-  if (platform === "linux") return { platform: "linux", arch: normalizedArch, extension: ".AppImage" };
-  throw new Error(`Rudder Desktop does not publish installers for ${platform}.`);
+  if (platform === "win32") return { platform: "windows", arch: "x64", extension: ".zip" };
+  if (platform === "linux") {
+    if (arch !== "x64") {
+      throw new Error(`Rudder Desktop does not publish portable assets for ${platform}/${arch}.`);
+    }
+    return { platform: "linux", arch: "x64", extension: ".AppImage" };
+  }
+  throw new Error(`Rudder Desktop does not publish portable assets for ${platform}.`);
+}
+function resolveDefaultDesktopInstallRoot(target, env = process.env, homeDir = homedir()) {
+  if (target.platform === "macos") return path9.join(homeDir, "Applications");
+  if (target.platform === "windows") {
+    const localAppData = env.LOCALAPPDATA?.trim() || path9.join(homeDir, "AppData", "Local");
+    return path9.join(localAppData, "Programs", DESKTOP_APP_NAME);
+  }
+  return path9.join(homeDir, ".local", "share", "rudder");
+}
+function resolveDesktopInstallPaths(target, installRoot) {
+  const root = path9.resolve(installRoot);
+  if (target.platform === "macos") {
+    const appPath2 = path9.join(root, `${DESKTOP_APP_NAME}.app`);
+    return {
+      installRoot: root,
+      appPath: appPath2,
+      executablePath: path9.join(appPath2, "Contents", "MacOS", DESKTOP_APP_NAME),
+      metadataPath: path9.join(root, DESKTOP_METADATA_FILE)
+    };
+  }
+  if (target.platform === "windows") {
+    return {
+      installRoot: root,
+      appPath: root,
+      executablePath: path9.join(root, `${DESKTOP_APP_NAME}.exe`),
+      metadataPath: path9.join(root, DESKTOP_METADATA_FILE)
+    };
+  }
+  const appPath = path9.join(root, `${DESKTOP_APP_NAME}.AppImage`);
+  return {
+    installRoot: root,
+    appPath,
+    executablePath: appPath,
+    metadataPath: path9.join(root, DESKTOP_METADATA_FILE)
+  };
 }
 function normalizeAssetName(name) {
   return name.toLowerCase().replaceAll("_", "-").replaceAll(" ", "-");
@@ -9979,6 +10047,7 @@ function scoreDesktopAsset(asset, target) {
   let score = 1;
   if (normalized.includes("rudder")) score += 2;
   if (normalized.includes(target.platform)) score += 4;
+  if (normalized.includes("portable")) score += 6;
   if (target.platform === "macos" && (normalized.includes("macos") || normalized.includes("darwin") || normalized.includes("mac-"))) {
     score += 4;
   }
@@ -10044,28 +10113,284 @@ function parseChecksumFile(contents) {
   }
   return checksums;
 }
-async function verifyChecksum(installerPath, checksumAsset, outputDir) {
-  if (!checksumAsset) return false;
+function resolveAssetChecksum(checksums, assetName) {
+  const expected = checksums.get(path9.basename(assetName));
+  if (!expected) {
+    throw new Error(`Desktop release checksums do not include ${path9.basename(assetName)}.`);
+  }
+  return expected;
+}
+function assertChecksumMatch(filePath, expected) {
+  const actual = checksumForFile(filePath);
+  if (actual !== expected.toLowerCase()) {
+    throw new Error(`Checksum mismatch for ${path9.basename(filePath)}.`);
+  }
+  return actual;
+}
+async function downloadChecksums(checksumAsset, outputDir) {
+  if (!checksumAsset) {
+    throw new Error("Desktop release is missing SHASUMS256.txt.");
+  }
   const checksumPath = await downloadAsset(checksumAsset, outputDir);
-  const checksums = parseChecksumFile(readFileSync(checksumPath, "utf8"));
-  const expected = checksums.get(path9.basename(installerPath));
-  if (!expected) return false;
-  const actual = checksumForFile(installerPath);
-  if (actual !== expected) {
-    throw new Error(`Checksum mismatch for ${path9.basename(installerPath)}.`);
+  return parseChecksumFile(readFileSync(checksumPath, "utf8"));
+}
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
   }
-  return true;
 }
-function openInstaller(installerPath, target) {
+function runChecked(command, args, options = {}) {
+  const result = spawnSync2(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options
+  });
+  if (result.status === 0) return;
+  const output = [result.stdout, result.stderr].filter((value) => typeof value === "string" && value.trim().length > 0).join("\n").trim();
+  throw new Error(`${command} ${args.join(" ")} failed${output ? `: ${output}` : ""}`);
+}
+function powershellQuote(value) {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+async function extractZip(zipPath, outputDir, target) {
+  await rm(outputDir, { recursive: true, force: true });
+  await mkdir(outputDir, { recursive: true });
+  if (target.platform === "macos") {
+    runChecked("ditto", ["-x", "-k", zipPath, outputDir]);
+    return;
+  }
+  if (target.platform === "windows") {
+    runChecked("powershell.exe", [
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      `Expand-Archive -LiteralPath ${powershellQuote(zipPath)} -DestinationPath ${powershellQuote(outputDir)} -Force`
+    ]);
+    return;
+  }
+  throw new Error(`Zip assets are not supported for ${target.platform}.`);
+}
+async function findPath(root, predicate, maxDepth = 5) {
+  async function visit(dir, depth) {
+    const entries = await readdir2(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path9.join(dir, entry.name);
+      if (predicate(fullPath, entry.isDirectory())) return fullPath;
+      if (entry.isDirectory() && depth < maxDepth) {
+        const nested = await visit(fullPath, depth + 1);
+        if (nested) return nested;
+      }
+    }
+    return null;
+  }
+  return await visit(root, 0);
+}
+async function findMacApp(extractDir) {
+  const direct = path9.join(extractDir, `${DESKTOP_APP_NAME}.app`);
+  if (await pathExists(direct)) return direct;
+  const found = await findPath(extractDir, (filePath, isDirectory) => isDirectory && path9.basename(filePath) === `${DESKTOP_APP_NAME}.app`);
+  if (!found) throw new Error(`Portable macOS archive did not contain ${DESKTOP_APP_NAME}.app.`);
+  return found;
+}
+async function findWindowsAppDir(extractDir) {
+  const direct = path9.join(extractDir, `${DESKTOP_APP_NAME}.exe`);
+  if (await pathExists(direct)) return extractDir;
+  const executable = await findPath(extractDir, (filePath, isDirectory) => !isDirectory && path9.basename(filePath).toLowerCase() === `${DESKTOP_APP_NAME.toLowerCase()}.exe`);
+  if (!executable) throw new Error(`Portable Windows archive did not contain ${DESKTOP_APP_NAME}.exe.`);
+  return path9.dirname(executable);
+}
+async function readInstallMetadata(metadataPath) {
+  try {
+    const parsed = JSON.parse(await readFile3(metadataPath, "utf8"));
+    if (parsed.version !== 1) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function isInstalledDesktopCurrent(metadata, releaseTag, assetName, assetChecksum) {
+  return Boolean(
+    metadata && metadata.releaseTag === releaseTag && metadata.assetName === assetName && metadata.assetChecksum === assetChecksum
+  );
+}
+function buildForceQuitCommand(target) {
+  if (target.platform === "windows") return { command: "taskkill.exe", args: ["/IM", `${DESKTOP_APP_NAME}.exe`, "/T", "/F"] };
+  return { command: "pkill", args: ["-x", DESKTOP_APP_NAME] };
+}
+function forceQuitDesktopProcesses(target) {
+  const command = buildForceQuitCommand(target);
+  spawnSync2(command.command, command.args, { stdio: "ignore" });
+}
+function isRunningInsideDesktopExecutable() {
+  return path9.basename(process.execPath).toLowerCase().startsWith(DESKTOP_APP_NAME.toLowerCase());
+}
+async function waitForUpdateQuitResponse(responsePath, timeoutMs = 8e3) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await pathExists(responsePath)) {
+      return JSON.parse(await readFile3(responsePath, "utf8"));
+    }
+    await delay(200);
+  }
+  return null;
+}
+async function requestDesktopQuit(executablePath, target) {
+  if (!await pathExists(executablePath)) return { ok: true, status: "not_running" };
+  const responsePath = path9.join(tmpdir(), `rudder-update-quit-${process.pid}-${Date.now()}.json`);
+  const result = spawnSync2(executablePath, [`${DESKTOP_UPDATE_QUIT_ARG}=${responsePath}`], {
+    stdio: "ignore",
+    timeout: 5e3
+  });
+  if (result.error && target.platform === "windows") {
+    return null;
+  }
+  try {
+    return await waitForUpdateQuitResponse(responsePath);
+  } finally {
+    await rm(responsePath, { force: true });
+  }
+}
+async function removePathWithRetry(targetPath, attempts = 5) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      await rm(targetPath, { recursive: true, force: true });
+      if (!await pathExists(targetPath)) return true;
+    } catch {
+    }
+    await delay(500);
+  }
+  return false;
+}
+async function prepareForDesktopReplace(paths, target) {
+  const hasManagedExecutable = await pathExists(paths.executablePath);
+  if (hasManagedExecutable) {
+    const quitResponse = await requestDesktopQuit(paths.executablePath, target);
+    if (quitResponse && !quitResponse.ok && quitResponse.status === "active_runs") {
+      throw new Error(
+        `Rudder Desktop has ${quitResponse.totalRuns} active run${quitResponse.totalRuns === 1 ? "" : "s"}. Stop active work, then rerun start.`
+      );
+    }
+    await delay(1e3);
+  } else if (!isRunningInsideDesktopExecutable()) {
+    forceQuitDesktopProcesses(target);
+  }
+  const replacePath = target.platform === "windows" ? paths.installRoot : paths.appPath;
+  if (await removePathWithRetry(replacePath)) return;
+  forceQuitDesktopProcesses(target);
+  await delay(1e3);
+  if (await removePathWithRetry(replacePath, 6)) return;
+  throw new Error(`Failed to replace existing Rudder Desktop at ${replacePath}. Close Rudder and rerun start.`);
+}
+async function installPortableDesktop(installerPath, paths, target) {
+  await mkdir(paths.installRoot, { recursive: true });
+  if (target.platform === "linux") {
+    await copyFile(installerPath, paths.appPath);
+    await chmod(paths.appPath, 493);
+    return;
+  }
+  const extractDir = await mkdtemp(path9.join(tmpdir(), "rudder-desktop-extract."));
+  try {
+    await extractZip(installerPath, extractDir, target);
+    if (target.platform === "macos") {
+      const appSource2 = await findMacApp(extractDir);
+      await cp(appSource2, paths.appPath, { recursive: true });
+      return;
+    }
+    const appSource = await findWindowsAppDir(extractDir);
+    await mkdir(path9.dirname(paths.installRoot), { recursive: true });
+    await cp(appSource, paths.installRoot, { recursive: true });
+  } finally {
+    await rm(extractDir, { recursive: true, force: true });
+  }
+}
+async function removeMacQuarantine(paths, target) {
+  if (target.platform !== "macos") return;
+  const result = spawnSync2("xattr", ["-dr", "com.apple.quarantine", paths.appPath], { stdio: "ignore" });
+  if (result.status !== 0) {
+    p13.log.warn(`Could not remove macOS quarantine attributes from ${paths.appPath}.`);
+  }
+}
+function quoteDesktopExec(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function buildLinuxDesktopEntry(executablePath) {
+  return [
+    "[Desktop Entry]",
+    "Type=Application",
+    "Name=Rudder",
+    `Exec=${quoteDesktopExec(executablePath)}`,
+    "Terminal=false",
+    "Categories=Development;",
+    ""
+  ].join("\n");
+}
+async function writeLinuxLaunchers(paths) {
+  const desktopDir = path9.join(homedir(), ".local", "share", "applications");
+  await mkdir(desktopDir, { recursive: true });
+  await writeFile2(path9.join(desktopDir, "rudder.desktop"), buildLinuxDesktopEntry(paths.executablePath), "utf8");
+  const binDir = path9.join(homedir(), ".local", "bin");
+  await mkdir(binDir, { recursive: true });
+  const wrapperPath = path9.join(binDir, "rudder-desktop");
+  const escaped = paths.executablePath.replaceAll("'", `'"'"'`);
+  await writeFile2(wrapperPath, `#!/bin/sh
+exec '${escaped}' "$@"
+`, "utf8");
+  await chmod(wrapperPath, 493);
+}
+function buildWindowsShortcutScript(executablePath) {
+  const appData = process.env.APPDATA?.trim() || path9.join(homedir(), "AppData", "Roaming");
+  const shortcutPath = path9.join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Rudder.lnk");
+  return [
+    "$shell = New-Object -ComObject WScript.Shell",
+    `$shortcut = $shell.CreateShortcut(${powershellQuote(shortcutPath)})`,
+    `$shortcut.TargetPath = ${powershellQuote(executablePath)}`,
+    `$shortcut.WorkingDirectory = ${powershellQuote(path9.dirname(executablePath))}`,
+    "$shortcut.Save()"
+  ].join("; ");
+}
+async function createPlatformLaunchers(paths, target) {
+  if (target.platform === "linux") {
+    await writeLinuxLaunchers(paths);
+    return;
+  }
+  if (target.platform === "windows") {
+    const result = spawnSync2("powershell.exe", [
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      buildWindowsShortcutScript(paths.executablePath)
+    ], { stdio: "ignore" });
+    if (result.status !== 0) p13.log.warn("Could not create the Windows Start Menu shortcut.");
+  }
+}
+function launchDesktop(paths, target) {
   if (target.platform === "macos") {
-    spawnSync2("open", [installerPath], { stdio: "inherit" });
+    spawn("open", [paths.appPath], { detached: true, stdio: "ignore" }).unref();
     return;
   }
   if (target.platform === "windows") {
-    spawnSync2("cmd.exe", ["/c", "start", "", installerPath], { stdio: "inherit" });
+    spawn("cmd.exe", ["/c", "start", "", paths.executablePath], { detached: true, stdio: "ignore" }).unref();
     return;
   }
-  spawnSync2("xdg-open", [installerPath], { stdio: "inherit" });
+  spawn(paths.executablePath, [], { detached: true, stdio: "ignore" }).unref();
+}
+async function writeInstallMetadata(paths, releaseTag, assetName, assetChecksum) {
+  mkdirSync2(path9.dirname(paths.metadataPath), { recursive: true });
+  const metadata = {
+    version: 1,
+    releaseTag,
+    assetName,
+    assetChecksum,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  mkdirSync2(paths.installRoot, { recursive: true });
+  await writeFile2(paths.metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, "utf8");
 }
 async function startCommand(opts) {
   const installCli = opts.cli !== false;
@@ -10084,8 +10409,11 @@ async function startCommand(opts) {
   if (installCli) {
     const installSpec = resolveCliInstallSpec(version);
     const command = `npm install --global ${installSpec}`;
+    const installedVersion = getGlobalInstalledPackageVersion(CLI_NPM_PACKAGE_NAME);
     p13.log.step("Preparing persistent CLI");
-    if (dryRun) {
+    if (isPersistentCliVersionCurrent(version, installedVersion)) {
+      p13.log.success(`${pc8.cyan("rudder")} CLI ${version} is already installed.`);
+    } else if (dryRun) {
       p13.log.message(`[dry-run] ${command}`);
     } else {
       p13.log.message(pc8.dim(`Running: ${command}`));
@@ -10100,32 +10428,45 @@ async function startCommand(opts) {
   if (installDesktop) {
     const target = resolveDesktopAssetTarget();
     const tag = resolveDesktopReleaseTag(version);
+    const installRoot = opts.desktopInstallDir ? path9.resolve(opts.desktopInstallDir) : resolveDefaultDesktopInstallRoot(target);
+    const installPaths = resolveDesktopInstallPaths(target, installRoot);
     const outputDir = opts.outputDir ? path9.resolve(opts.outputDir) : await mkdtemp(path9.join(tmpdir(), "rudder-desktop-installer."));
-    p13.log.step("Starting desktop app");
+    p13.log.step("Installing desktop app");
     p13.log.message(`Release: ${pc8.cyan(`${repo}@${tag}`)}`);
     p13.log.message(`Target: ${pc8.cyan(`${target.platform}/${target.arch}`)}`);
+    p13.log.message(`Install: ${pc8.cyan(installPaths.appPath)}`);
     if (dryRun) {
-      p13.log.message(`[dry-run] Would resolve and download/open the matching desktop installer to ${outputDir}`);
+      p13.log.message(`[dry-run] Would resolve, download, verify, install, and ${opts.open === false ? "not launch" : "launch"} Rudder Desktop.`);
       p13.outro(pc8.green("Dry run complete."));
       return;
     }
     const release = await fetchGithubRelease(repo, tag);
     const asset = selectDesktopAsset(release.assets ?? [], target);
     if (!asset) {
-      throw new Error(`No Rudder Desktop installer found for ${target.platform}/${target.arch} in ${repo}@${release.tag_name}.`);
-    }
-    const installerPath = await downloadAsset(asset, outputDir);
-    const checksumVerified = await verifyChecksum(installerPath, selectChecksumAsset(release.assets ?? []), outputDir);
-    if (target.platform === "linux") {
-      await chmod(installerPath, 493);
+      throw new Error(`No Rudder Desktop portable asset found for ${target.platform}/${target.arch} in ${repo}@${release.tag_name}.`);
+    }
+    const checksums = await downloadChecksums(selectChecksumAsset(release.assets ?? []), outputDir);
+    const expectedChecksum = resolveAssetChecksum(checksums, asset.name);
+    const metadata = await readInstallMetadata(installPaths.metadataPath);
+    if (isInstalledDesktopCurrent(metadata, release.tag_name, asset.name, expectedChecksum) && await pathExists(installPaths.executablePath)) {
+      p13.log.success(`Rudder Desktop is already installed at ${pc8.cyan(installPaths.appPath)}.`);
+      await removeMacQuarantine(installPaths, target);
+      await createPlatformLaunchers(installPaths, target);
+    } else {
+      const installerPath = await downloadAsset(asset, outputDir);
+      const checksum = assertChecksumMatch(installerPath, expectedChecksum);
+      p13.log.success(`Downloaded and verified ${pc8.cyan(path9.basename(installerPath))}`);
+      p13.log.message("Replacing existing Rudder Desktop if needed.");
+      await prepareForDesktopReplace(installPaths, target);
+      await installPortableDesktop(installerPath, installPaths, target);
+      await removeMacQuarantine(installPaths, target);
+      await createPlatformLaunchers(installPaths, target);
+      await writeInstallMetadata(installPaths, release.tag_name, asset.name, checksum);
+      p13.log.success(`Installed Rudder Desktop to ${pc8.cyan(installPaths.appPath)}.`);
     }
-    p13.log.success(`Downloaded ${pc8.cyan(path9.basename(installerPath))}`);
-    if (checksumVerified) p13.log.success("Verified SHA-256 checksum.");
     if (opts.open !== false) {
-      openInstaller(installerPath, target);
-      p13.log.message(`Installer path: ${pc8.cyan(installerPath)}`);
-    } else {
-      p13.log.message(`Installer path: ${pc8.cyan(installerPath)}`);
+      launchDesktop(installPaths, target);
+      p13.log.success("Rudder Desktop launched.");
     }
   }
   p13.outro(pc8.green("Rudder start complete."));
@@ -10167,7 +10508,7 @@ async function addAllowedHostname(host, opts) {
 }
 
 // src/commands/heartbeat-run.ts
-import { setTimeout as delay } from "node:timers/promises";
+import { setTimeout as delay2 } from "node:timers/promises";
 import pc19 from "picocolors";
 
 // ../packages/agent-runtimes/claude-local/src/cli/format-event.ts
@@ -11160,7 +11501,7 @@ function getCLIAdapter(type) {
 import pc18 from "picocolors";
 
 // src/client/board-auth.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import fs10 from "node:fs";
 import path10 from "node:path";
 import pc17 from "picocolors";
@@ -11277,16 +11618,16 @@ function openUrl(url) {
   const platform = process.platform;
   try {
     if (platform === "darwin") {
-      const child2 = spawn("open", [url], { detached: true, stdio: "ignore" });
+      const child2 = spawn2("open", [url], { detached: true, stdio: "ignore" });
       child2.unref();
       return true;
     }
     if (platform === "win32") {
-      const child2 = spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" });
+      const child2 = spawn2("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" });
       child2.unref();
       return true;
     }
-    const child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+    const child = spawn2("xdg-open", [url], { detached: true, stdio: "ignore" });
     child.unref();
     return true;
   } catch {
@@ -12015,7 +12356,7 @@ async function heartbeatRun(opts) {
         logOffset += Buffer.byteLength(logResult.content, "utf8");
       }
     }
-    await delay(POLL_INTERVAL_MS);
+    await delay2(POLL_INTERVAL_MS);
   }
   if (finalStatus) {
     if (!debug && stdoutJsonBuffer.trim()) {
@@ -12230,7 +12571,7 @@ function registerContextCommands(program) {
 }
 
 // src/commands/client/company.ts
-import { mkdir, readdir as readdir2, readFile as readFile3, stat, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, readdir as readdir3, readFile as readFile4, stat, writeFile as writeFile3 } from "node:fs/promises";
 import path14 from "node:path";
 import * as p16 from "@clack/prompts";
 import pc22 from "picocolors";
@@ -12963,7 +13304,7 @@ function normalizeGithubImportSource(input, refOverride) {
   }
   return buildGithubImportUrl({ owner, repo, ref });
 }
-async function pathExists(inputPath) {
+async function pathExists2(inputPath) {
   try {
     await stat(path14.resolve(inputPath));
     return true;
@@ -12972,7 +13313,7 @@ async function pathExists(inputPath) {
   }
 }
 async function collectPackageFiles(root, current, files) {
-  const entries = await readdir2(current, { withFileTypes: true });
+  const entries = await readdir3(current, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.name.startsWith(".git")) continue;
     const absolutePath = path14.join(current, entry.name);
@@ -12983,14 +13324,14 @@ async function collectPackageFiles(root, current, files) {
     if (!entry.isFile()) continue;
     const relativePath = path14.relative(root, absolutePath).replace(/\\/g, "/");
     if (!shouldIncludePortableFile(relativePath)) continue;
-    files[relativePath] = readPortableFileEntry(relativePath, await readFile3(absolutePath));
+    files[relativePath] = readPortableFileEntry(relativePath, await readFile4(absolutePath));
   }
 }
 async function resolveInlineSourceFromPath(inputPath) {
   const resolved = path14.resolve(inputPath);
   const resolvedStat = await stat(resolved);
   if (resolvedStat.isFile() && path14.extname(resolved).toLowerCase() === ".zip") {
-    const archive = await readZipArchive(await readFile3(resolved));
+    const archive = await readZipArchive(await readFile4(resolved));
     const filteredFiles = Object.fromEntries(
       Object.entries(archive.files).filter(([relativePath]) => shouldIncludePortableFile(relativePath))
     );
@@ -13009,16 +13350,16 @@ async function resolveInlineSourceFromPath(inputPath) {
 }
 async function writeExportToFolder(outDir, exported) {
   const root = path14.resolve(outDir);
-  await mkdir(root, { recursive: true });
+  await mkdir2(root, { recursive: true });
   for (const [relativePath, content] of Object.entries(exported.files)) {
     const normalized = relativePath.replace(/\\/g, "/");
     const filePath = path14.join(root, normalized);
-    await mkdir(path14.dirname(filePath), { recursive: true });
+    await mkdir2(path14.dirname(filePath), { recursive: true });
     const writeValue = portableFileEntryToWriteValue(content);
     if (typeof writeValue === "string") {
-      await writeFile2(filePath, writeValue, "utf8");
+      await writeFile3(filePath, writeValue, "utf8");
     } else {
-      await writeFile2(filePath, writeValue);
+      await writeFile3(filePath, writeValue);
     }
   }
 }
@@ -13029,7 +13370,7 @@ async function confirmOverwriteExportDirectory(outDir) {
   if (!stats.isDirectory()) {
     throw new Error(`Export output path ${root} exists and is not a directory.`);
   }
-  const entries = await readdir2(root);
+  const entries = await readdir3(root);
   if (entries.length === 0) return;
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw new Error(`Export output directory ${root} already contains files. Re-run interactively or choose an empty directory.`);
@@ -13226,7 +13567,7 @@ function registerCompanyCommands(program) {
           throw new Error("Target existing organization requires --org-id (or context default orgId).");
         }
         let sourcePayload;
-        const treatAsLocalPath = !isHttpUrl(from) && await pathExists(from);
+        const treatAsLocalPath = !isHttpUrl(from) && await pathExists2(from);
         const isGithubSource = isGithubUrl(from) || isGithubShorthand(from) && !treatAsLocalPath;
         if (isHttpUrl(from) || isGithubSource) {
           if (!isGithubUrl(from) && !isGithubShorthand(from)) {
@@ -14272,7 +14613,7 @@ function filterIssueRows(rows, match) {
 init_src();
 
 // ../packages/agent-runtime-utils/src/server-utils.ts
-import { constants as fsConstants, promises as fs12 } from "node:fs";
+import { constants as fsConstants2, promises as fs12 } from "node:fs";
 import path15 from "node:path";
 var MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 var MAX_EXCERPT_BYTES = 32 * 1024;
@@ -19173,7 +19514,7 @@ var DATA_DIR_OPTION_HELP = "Rudder data directory root (isolates state from ~/.r
 var LOCAL_ENV_OPTION_HELP = "Local environment profile (dev, prod_local, e2e)";
 function createProgram() {
   const program = new Command();
-  program.name("rudder").description("Rudder CLI \u2014 setup, diagnose, and configure your instance").version("0.1.0-canary.2");
+  program.name("rudder").description("Rudder CLI \u2014 setup, diagnose, and configure your instance").version("0.1.0-canary.4");
   program.option("--local-env <name>", LOCAL_ENV_OPTION_HELP);
   program.hook("preAction", (_thisCommand, actionCommand) => {
     const options = actionCommand.optsWithGlobals();
@@ -19185,7 +19526,7 @@ function createProgram() {
     });
     loadRudderEnvFile(options.config);
   });
-  program.command("start").description("Start Rudder Desktop and prepare the matching persistent CLI").option("--no-cli", "Skip persistent CLI installation").option("--no-desktop", "Skip desktop app installation").option("--version <version>", "Rudder version to start (default: current CLI version)").option("--repo <owner/repo>", "GitHub repository that hosts desktop releases").option("--output-dir <path>", "Directory for the downloaded desktop installer").option("--no-open", "Download the desktop installer without opening it").option("--no-version-check", "Skip checking npm for a newer Rudder CLI version").option("--dry-run", "Print the start actions without changing the machine", false).action(startCommand);
+  program.command("start").description("Start Rudder Desktop and prepare the matching persistent CLI").option("--no-cli", "Skip persistent CLI installation").option("--no-desktop", "Skip desktop app installation").option("--version <version>", "Rudder version to start (default: current CLI version)").option("--repo <owner/repo>", "GitHub repository that hosts desktop releases").option("--output-dir <path>", "Directory for downloaded desktop release assets").option("--desktop-install-dir <path>", "Directory for the portable Desktop install").option("--no-open", "Install Desktop without launching it").option("--no-version-check", "Skip checking npm for a newer Rudder CLI version").option("--dry-run", "Print the start actions without changing the machine", false).action(startCommand);
   program.command("onboard").description("Interactive first-run setup wizard").option("-c, --config <path>", "Path to config file").option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP).option("-y, --yes", "Accept defaults (quickstart + start immediately)", false).option("--run", "Start Rudder immediately after saving config", false).action(onboard);
   program.command("doctor").description("Run diagnostic checks on your Rudder setup").option("-c, --config <path>", "Path to config file").option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP).option("--repair", "Attempt to repair issues automatically").alias("--fix").option("-y, --yes", "Skip repair confirmation prompts").action(async (opts) => {
     await doctor(opts);