@rudderhq/cli 0.3.6-canary.9 → 0.4.1

package/dist/index.js

@@ -572,6 +572,13 @@ var init_constants = __esm({
   }
 });
 
+// ../packages/shared/dist/agent-run.js
+var init_agent_run = __esm({
+  "../packages/shared/dist/agent-run.js"() {
+    "use strict";
+  }
+});
+
 // ../packages/shared/dist/types/observability.js
 var init_observability = __esm({
   "../packages/shared/dist/types/observability.js"() {
@@ -607,6 +614,7 @@ var init_instance = __esm({
     }).strict();
     patchInstanceNotificationSettingsSchema = instanceNotificationSettingsSchema.partial();
     instanceLangfuseSettingsSchema = z.object({
+      installed: z.boolean().default(false),
       enabled: z.boolean().default(false),
       baseUrl: z.string().url().default("http://localhost:3000"),
       publicKey: z.string().default(""),
@@ -784,7 +792,7 @@ var init_adapter_skills = __esm({
 
 // ../packages/shared/dist/validators/chat.js
 import { z as z4 } from "zod";
-var chatConversationStatusSchema, chatIssueCreationModeSchema, chatMessageRoleSchema, chatMessageKindSchema, chatMessageStatusSchema, chatContextEntityTypeSchema, createChatContextLinkSchema, createChatConversationSchema, setChatProjectContextSchema, updateChatConversationSchema, addChatMessageSchema, chatRichReferenceDisplaySchema, chatIssueIdentifierSchema, chatAskUserIdentifierSchema, chatAskUserOptionSchema, chatAskUserQuestionSchema, chatAskUserRequestSchema, chatIssueRichReferenceSchema, chatIssueCommentRichReferenceSchema, chatRichReferenceSchema, chatRichReferencesSchema, chatAutomationCreateSchema, createChatAttachmentMetadataSchema, chatIssueProposalSchema, convertChatToIssueSchema, chatOperationProposalSchema, resolveChatOperationProposalSchema, updateChatConversationUserStateSchema, updateMessengerThreadUserStateSchema, createMessengerCustomGroupSchema, createMessengerCustomGroupWithEntriesSchema, updateMessengerCustomGroupSchema, reorderMessengerCustomGroupsSchema, assignMessengerCustomGroupEntrySchema, reorderMessengerCustomGroupEntriesSchema;
+var chatConversationStatusSchema, chatIssueCreationModeSchema, chatMessageRoleSchema, chatMessageKindSchema, chatMessageStatusSchema, chatContextEntityTypeSchema, createChatContextLinkSchema, createChatConversationSchema, setChatProjectContextSchema, updateChatConversationSchema, forkChatConversationSchema, addChatMessageSchema, chatQueuedMessagePayloadSchema, createChatQueuedMessageSchema, updateChatQueuedMessageSchema, cancelChatQueuedMessageSchema, steerChatQueuedMessageSchema, chatRichReferenceDisplaySchema, chatIssueIdentifierSchema, chatAskUserIdentifierSchema, chatAskUserOptionSchema, chatAskUserQuestionSchema, chatAskUserRequestSchema, chatIssueRichReferenceSchema, chatIssueCommentRichReferenceSchema, chatRichReferenceSchema, chatRichReferencesSchema, chatAutomationCreateSchema, createChatAttachmentMetadataSchema, chatIssueProposalSchema, convertChatToIssueSchema, chatOperationProposalSchema, resolveChatOperationProposalSchema, updateChatConversationUserStateSchema, updateMessengerThreadUserStateSchema, createMessengerCustomGroupSchema, createMessengerCustomGroupWithEntriesSchema, updateMessengerCustomGroupSchema, reorderMessengerCustomGroupsSchema, assignMessengerCustomGroupEntrySchema, reorderMessengerCustomGroupEntriesSchema;
 var init_chat = __esm({
   "../packages/shared/dist/validators/chat.js"() {
     "use strict";
@@ -817,9 +825,39 @@ var init_chat = __esm({
       primaryIssueId: z4.string().uuid().optional().nullable(),
       resolvedAt: z4.string().datetime().optional().nullable()
     });
+    forkChatConversationSchema = z4.object({
+      sourceMessageId: z4.string().uuid().optional().nullable(),
+      title: z4.string().trim().min(1).max(200).optional()
+    });
     addChatMessageSchema = z4.object({
       body: z4.string().trim().min(1).max(2e4),
-      editUserMessageId: z4.string().uuid().optional().nullable()
+      editUserMessageId: z4.string().uuid().optional().nullable(),
+      queuedMessageId: z4.string().uuid().optional().nullable()
+    });
+    chatQueuedMessagePayloadSchema = z4.object({
+      body: z4.string().trim().min(1).max(2e4),
+      attachmentIds: z4.array(z4.string().uuid()).optional().default([]),
+      projectId: z4.string().uuid().optional().nullable(),
+      skillRefs: z4.array(z4.string().trim().min(1).max(240)).optional().default([]),
+      accessMode: z4.string().trim().min(1).max(120).optional().nullable(),
+      model: z4.string().trim().min(1).max(120).optional().nullable(),
+      effort: z4.string().trim().min(1).max(120).optional().nullable(),
+      metadata: z4.record(z4.unknown()).optional().nullable()
+    });
+    createChatQueuedMessageSchema = z4.object({
+      clientMutationId: z4.string().trim().min(1).max(120),
+      expectedGenerationId: z4.string().uuid().optional().nullable(),
+      payload: chatQueuedMessagePayloadSchema
+    });
+    updateChatQueuedMessageSchema = z4.object({
+      version: z4.number().int().positive(),
+      payload: chatQueuedMessagePayloadSchema
+    });
+    cancelChatQueuedMessageSchema = z4.object({
+      version: z4.number().int().positive().optional()
+    });
+    steerChatQueuedMessageSchema = z4.object({
+      expectedActiveGenerationId: z4.string().uuid().optional().nullable()
     });
     chatRichReferenceDisplaySchema = z4.enum(["card", "inline"]);
     chatIssueIdentifierSchema = z4.string().trim().min(1).max(64).regex(/^[A-Z0-9][A-Z0-9-]*$/i);
@@ -972,12 +1010,14 @@ var init_chat = __esm({
       icon: z4.string().trim().min(1).max(24).optional().nullable()
     });
     createMessengerCustomGroupWithEntriesSchema = createMessengerCustomGroupSchema.extend({
-      threadKeys: z4.array(z4.string().trim().min(1).max(240)).min(1).max(50)
+      threadKeys: z4.array(z4.string().trim().min(1).max(240)).min(1).max(50),
+      autoGenerateName: z4.boolean().optional()
     });
     updateMessengerCustomGroupSchema = z4.object({
       name: z4.string().trim().min(1).max(80).optional(),
       icon: z4.string().trim().min(1).max(24).optional().nullable(),
       collapsed: z4.boolean().optional(),
+      pinned: z4.boolean().optional(),
       sortOrder: z4.number().int().min(0).optional()
     });
     reorderMessengerCustomGroupsSchema = z4.object({
@@ -2985,6 +3025,7 @@ var init_api = __esm({
       secrets: `${API_PREFIX}/secrets`,
       costs: `${API_PREFIX}/costs`,
       activity: `${API_PREFIX}/activity`,
+      agentRuns: `${API_PREFIX}/agent-runs`,
       dashboard: `${API_PREFIX}/dashboard`,
       sidebarBadges: `${API_PREFIX}/sidebar-badges`,
       invites: `${API_PREFIX}/invites`,
@@ -3183,6 +3224,7 @@ var init_config_schema = __esm({
       })
     });
     langfuseConfigSchema = z28.object({
+      installed: z28.boolean().optional(),
       enabled: z28.boolean().default(false),
       baseUrl: z28.string().url().default("http://localhost:3000"),
       publicKey: z28.string().optional(),
@@ -3260,6 +3302,7 @@ var init_dist = __esm({
   "../packages/shared/dist/index.js"() {
     "use strict";
     init_constants();
+    init_agent_run();
     init_observability();
     init_workspace_backup();
     init_validators();
@@ -3491,8 +3534,8 @@ var init_env = __esm({
 });
 
 // src/runtime/install.ts
-import { spawnSync } from "node:child_process";
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { execFileSync, spawnSync } from "node:child_process";
+import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import path4 from "node:path";
 import { pathToFileURL } from "node:url";
@@ -3561,23 +3604,6 @@ async function hasRequiredRuntimePlatformDependencies(cacheDir) {
   if (!platformPackage) return true;
   return await canResolveRuntimePackage(cacheDir, platformPackage);
 }
-async function assertRequiredRuntimePlatformDependencies(cacheDir, command, output) {
-  if (!await canResolveRuntimePackage(cacheDir, EMBEDDED_POSTGRES_PACKAGE_NAME)) return;
-  const platformPackage = resolveEmbeddedPostgresPlatformPackage();
-  if (!platformPackage || await canResolveRuntimePackage(cacheDir, platformPackage)) return;
-  throw new RuntimeInstallError(
-    `Rudder runtime installation is missing required platform package ${platformPackage}. Re-run manually: ${command}`,
-    {
-      cacheDir,
-      command,
-      output: [
-        output,
-        `Missing required optional dependency: ${platformPackage}`,
-        "Your npm registry, mirror, proxy, or cache may have skipped the embedded PostgreSQL platform package."
-      ].filter((line) => line.trim().length > 0).join("\n")
-    }
-  );
-}
 async function isRuntimeCacheHit(options) {
   const packageName = options.packageName ?? RUNTIME_NPM_PACKAGE_NAME;
   const packageVersion = resolveRuntimePackageVersion(options.version);
@@ -3600,7 +3626,9 @@ async function ensureRuntimeInstalled(options) {
   const cacheDir = resolveRuntimeCacheDir(packageVersion, options.homeDir);
   const packageSpec = resolveRuntimePackageSpec(packageVersion, packageName);
   const command = formatRuntimeInstallCommand(cacheDir, packageSpec);
+  const preparePostgresPayload = options.preparePostgresPayload === true;
   if (await isRuntimeCacheHit({ cacheDir, version: packageVersion, packageName })) {
+    const postgresPayload2 = await stageRuntimePostgresPayload(cacheDir, preparePostgresPayload);
     await touchRuntimeInstallMetadata(cacheDir);
     const prune2 = await maybePruneRuntimeCache({
       homeDir: options.homeDir,
@@ -3608,37 +3636,75 @@ async function ensureRuntimeInstalled(options) {
       enabled: options.pruneRuntimeCache !== false,
       retention: options.retention
     });
-    return { status: "hit", cacheDir, packageSpec, command, output: "", ...prune2 ? { prune: prune2 } : {} };
+    return withPostgresPayload(
+      { status: "hit", cacheDir, packageSpec, command, output: "", ...prune2 ? { prune: prune2 } : {} },
+      postgresPayload2
+    );
+  }
+  const spawnSyncImpl = options.spawnSyncImpl ?? spawnSync;
+  const existingRuntimeOutput = await tryRepairExistingRuntimePackage({
+    spawnSyncImpl,
+    cacheDir,
+    packageName,
+    packageVersion
+  });
+  if (existingRuntimeOutput !== null) {
+    const postgresPayload2 = await stageRuntimePostgresPayload(cacheDir, preparePostgresPayload);
+    const metadata2 = {
+      version: 1,
+      packageName,
+      packageVersion,
+      installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      lastUsedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeRuntimeInstallMetadata(cacheDir, metadata2);
+    const prune2 = await maybePruneRuntimeCache({
+      homeDir: options.homeDir,
+      requestedVersion: packageVersion,
+      enabled: options.pruneRuntimeCache !== false,
+      retention: options.retention
+    });
+    return withPostgresPayload(
+      { status: "installed", cacheDir, packageSpec, command, output: existingRuntimeOutput, ...prune2 ? { prune: prune2 } : {} },
+      postgresPayload2
+    );
   }
   await rm(cacheDir, { recursive: true, force: true });
   await mkdir(cacheDir, { recursive: true });
-  await writeFile(path4.join(cacheDir, "package.json"), `${JSON.stringify({ private: true, type: "module" }, null, 2)}
+  await writeFile(path4.join(cacheDir, "package.json"), `${JSON.stringify(RUNTIME_CACHE_PACKAGE_JSON, null, 2)}
 `, "utf8");
-  const spawnSyncImpl = options.spawnSyncImpl ?? spawnSync;
   const result = runNpmRuntimeInstall(spawnSyncImpl, cacheDir, packageSpec);
-  const output = collectSpawnOutput(result);
+  let output = collectSpawnOutput(result);
   if (result.status !== 0 && packageVersion !== "latest" && isVersionNotFoundError(output)) {
     const fallbackVersion = "latest";
     const fallbackCacheDir = resolveRuntimeCacheDir(fallbackVersion, options.homeDir);
     const fallbackSpec = resolveRuntimePackageSpec(fallbackVersion, packageName);
     if (await isRuntimeCacheHit({ cacheDir: fallbackCacheDir, version: fallbackVersion, packageName })) {
+      const fallbackPostgresPayload = await stageRuntimePostgresPayload(fallbackCacheDir, preparePostgresPayload);
       await touchRuntimeInstallMetadata(fallbackCacheDir);
-      return {
-        status: "hit",
-        cacheDir: fallbackCacheDir,
-        packageSpec: fallbackSpec,
-        command: formatRuntimeInstallCommand(fallbackCacheDir, fallbackSpec),
-        output: ""
-      };
+      return withPostgresPayload(
+        {
+          status: "hit",
+          cacheDir: fallbackCacheDir,
+          packageSpec: fallbackSpec,
+          command: formatRuntimeInstallCommand(fallbackCacheDir, fallbackSpec),
+          output: ""
+        },
+        fallbackPostgresPayload
+      );
     }
     await rm(fallbackCacheDir, { recursive: true, force: true });
     await mkdir(fallbackCacheDir, { recursive: true });
-    await writeFile(path4.join(fallbackCacheDir, "package.json"), `${JSON.stringify({ private: true, type: "module" }, null, 2)}
+    await writeFile(path4.join(fallbackCacheDir, "package.json"), `${JSON.stringify(RUNTIME_CACHE_PACKAGE_JSON, null, 2)}
 `, "utf8");
     const fallbackResult = runNpmRuntimeInstall(spawnSyncImpl, fallbackCacheDir, fallbackSpec);
-    const fallbackOutput = collectSpawnOutput(fallbackResult);
+    let fallbackOutput = collectSpawnOutput(fallbackResult);
     if (fallbackResult.status === 0) {
-      await assertRequiredRuntimePlatformDependencies(fallbackCacheDir, formatRuntimeInstallCommand(fallbackCacheDir, fallbackSpec), fallbackOutput);
+      fallbackOutput = collectOutputParts(
+        fallbackOutput,
+        await ensureRequiredEmbeddedPostgresPlatformPackage(spawnSyncImpl, fallbackCacheDir)
+      );
+      const postgresPayload2 = await stageRuntimePostgresPayload(fallbackCacheDir, preparePostgresPayload);
       const fallbackMetadata = {
         version: 1,
         packageName,
@@ -3647,13 +3713,16 @@ async function ensureRuntimeInstalled(options) {
         lastUsedAt: (/* @__PURE__ */ new Date()).toISOString()
       };
       await writeRuntimeInstallMetadata(fallbackCacheDir, fallbackMetadata);
-      return {
-        status: "installed",
-        cacheDir: fallbackCacheDir,
-        packageSpec: fallbackSpec,
-        command: formatRuntimeInstallCommand(fallbackCacheDir, fallbackSpec),
-        output: fallbackOutput
-      };
+      return withPostgresPayload(
+        {
+          status: "installed",
+          cacheDir: fallbackCacheDir,
+          packageSpec: fallbackSpec,
+          command: formatRuntimeInstallCommand(fallbackCacheDir, fallbackSpec),
+          output: fallbackOutput
+        },
+        postgresPayload2
+      );
     }
   }
   if (result.status !== 0) {
@@ -3662,7 +3731,11 @@ async function ensureRuntimeInstalled(options) {
       { cacheDir, command, output }
     );
   }
-  await assertRequiredRuntimePlatformDependencies(cacheDir, command, output);
+  output = collectOutputParts(
+    output,
+    await ensureRequiredEmbeddedPostgresPlatformPackage(spawnSyncImpl, cacheDir)
+  );
+  const postgresPayload = await stageRuntimePostgresPayload(cacheDir, preparePostgresPayload);
   const metadata = {
     version: 1,
     packageName,
@@ -3677,7 +3750,13 @@ async function ensureRuntimeInstalled(options) {
     enabled: options.pruneRuntimeCache !== false,
     retention: options.retention
   });
-  return { status: "installed", cacheDir, packageSpec, command, output, ...prune ? { prune } : {} };
+  return withPostgresPayload(
+    { status: "installed", cacheDir, packageSpec, command, output, ...prune ? { prune } : {} },
+    postgresPayload
+  );
+}
+function resolveRuntimePostgresPayloadBinDir(cacheDir, platform = process.platform, arch = process.arch) {
+  return path4.join(cacheDir, RUNTIME_POSTGRES_PAYLOAD_DIR, runtimePostgresPlatformSegment(platform, arch), "bin");
 }
 function resolveRuntimeServerEntrypoint(cacheDir, packageName = RUNTIME_NPM_PACKAGE_NAME) {
   return createRequire(path4.join(cacheDir, "package.json")).resolve(packageName);
@@ -3700,9 +3779,204 @@ function runNpmRuntimeInstall(spawnSyncImpl, cacheDir, packageSpec) {
 function formatRuntimeInstallCommand(cacheDir, packageSpec) {
   return `npm install --prefix ${cacheDir} ${RUNTIME_NPM_INSTALL_FLAGS.join(" ")} ${packageSpec}`;
 }
+function formatRuntimePlatformRepairCommand(cacheDir, packageSpec) {
+  return `npm pack ${packageSpec} --registry=${NPM_PUBLIC_REGISTRY_URL} --silent, then extract it into ${path4.join(cacheDir, "node_modules")}`;
+}
 function collectSpawnOutput(result) {
   return [result.stdout, result.stderr, result.error instanceof Error ? result.error.message : null].filter((value) => typeof value === "string" && value.trim().length > 0).join("\n").trim();
 }
+function collectOutputParts(...parts) {
+  return parts.filter((part) => part.trim().length > 0).join("\n").trim();
+}
+function withPostgresPayload(result, postgresPayload) {
+  return {
+    ...result,
+    output: collectOutputParts(result.output, postgresPayload.output),
+    ...postgresPayload.binDir ? { postgresPayloadBinDir: postgresPayload.binDir } : {}
+  };
+}
+function runtimePackageJsonPath(cacheDir, packageName) {
+  return path4.join(cacheDir, "node_modules", ...packageName.split("/"), "package.json");
+}
+async function readRuntimePackageJson(cacheDir, packageName) {
+  try {
+    return JSON.parse(await readFile(runtimePackageJsonPath(cacheDir, packageName), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function tryRepairExistingRuntimePackage(options) {
+  const runtimePackage = await readRuntimePackageJson(options.cacheDir, options.packageName);
+  if (!runtimePackage) return null;
+  if (options.packageVersion !== "latest" && runtimePackage.version !== options.packageVersion) return null;
+  const output = await ensureRequiredEmbeddedPostgresPlatformPackage(options.spawnSyncImpl, options.cacheDir);
+  return await hasRequiredRuntimePlatformDependencies(options.cacheDir) ? output : null;
+}
+async function resolveEmbeddedPostgresPlatformPackageSpec(cacheDir) {
+  if (!await canResolveRuntimePackage(cacheDir, EMBEDDED_POSTGRES_PACKAGE_NAME)) return null;
+  const packageName = resolveEmbeddedPostgresPlatformPackage();
+  if (!packageName) return null;
+  const embeddedPostgresPackage = await readRuntimePackageJson(cacheDir, EMBEDDED_POSTGRES_PACKAGE_NAME);
+  const versionRange = embeddedPostgresPackage?.optionalDependencies?.[packageName];
+  const packageVersion = normalizeOptionalDependencyVersion(versionRange);
+  return packageVersion ? `${packageName}@${packageVersion}` : packageName;
+}
+async function ensureRequiredEmbeddedPostgresPlatformPackage(spawnSyncImpl, cacheDir) {
+  const packageSpec = await resolveEmbeddedPostgresPlatformPackageSpec(cacheDir);
+  if (!packageSpec) return "";
+  const packageName = packageNameFromSpec(packageSpec);
+  if (packageName && await canResolveRuntimePackage(cacheDir, packageName)) return "";
+  await removeRuntimeInstallLocks(cacheDir);
+  const result = await installRuntimePackageInStaging(spawnSyncImpl, cacheDir, packageSpec, packageName);
+  const output = collectSpawnOutput(result);
+  if (result.status === 0 && packageName && await canResolveRuntimePackage(cacheDir, packageName)) {
+    return output;
+  }
+  const command = formatRuntimePlatformRepairCommand(cacheDir, packageSpec);
+  throw new RuntimeInstallError(
+    `Rudder runtime installation is missing required platform package ${packageName || packageSpec}. Re-run manually: ${command}`,
+    { cacheDir, command, output }
+  );
+}
+async function installRuntimePackageInStaging(spawnSyncImpl, cacheDir, packageSpec, packageName) {
+  const stagingDir = path4.join(cacheDir, `.platform-repair-${process.pid}-${Date.now()}`);
+  await mkdir(stagingDir, { recursive: true });
+  try {
+    const packResult = runNpmPack(spawnSyncImpl, packageSpec, stagingDir);
+    if (packResult.status !== 0) return packResult;
+    const packFilename = parseNpmPackFilename(packResult.stdout);
+    if (!packFilename) {
+      return createSyntheticSpawnResult(1, "", `Unable to parse npm pack output for ${packageSpec}.`);
+    }
+    const archivePath = path4.join(stagingDir, packFilename);
+    const targetDir = path4.dirname(runtimePackageJsonPath(cacheDir, packageName));
+    await mkdir(path4.dirname(targetDir), { recursive: true });
+    await rm(targetDir, { recursive: true, force: true });
+    await mkdir(targetDir, { recursive: true });
+    const extractResult = runTarExtract(spawnSyncImpl, archivePath, targetDir);
+    return combineSpawnResults(packResult, extractResult);
+  } finally {
+    await rm(stagingDir, { recursive: true, force: true });
+  }
+}
+function runNpmPack(spawnSyncImpl, packageSpec, destinationDir) {
+  return spawnSyncImpl(
+    process.platform === "win32" ? "npm.cmd" : "npm",
+    ["pack", packageSpec, "--pack-destination", destinationDir, ...RUNTIME_NPM_PACK_FLAGS],
+    {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...NPM_PLATFORM_REPAIR_ENV },
+      ...process.platform === "win32" ? { shell: true, windowsHide: true } : {}
+    }
+  );
+}
+function runTarExtract(spawnSyncImpl, archivePath, targetDir) {
+  return spawnSyncImpl(
+    "tar",
+    ["-xzf", archivePath, "-C", targetDir, "--strip-components", "1"],
+    {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...process.platform === "win32" ? { windowsHide: true } : {}
+    }
+  );
+}
+function parseNpmPackFilename(stdout) {
+  if (typeof stdout !== "string") return null;
+  const filename = stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
+  return filename?.endsWith(".tgz") ? filename : null;
+}
+function createSyntheticSpawnResult(status, stdout, stderr) {
+  return { status, stdout, stderr };
+}
+function combineSpawnResults(...results) {
+  const last = results.at(-1);
+  return {
+    status: last?.status ?? 0,
+    stdout: results.map((result) => result.stdout).filter(Boolean).join("\n"),
+    stderr: results.map((result) => result.stderr).filter(Boolean).join("\n"),
+    error: results.find((result) => result.error)?.error
+  };
+}
+async function removeRuntimeInstallLocks(cacheDir) {
+  await Promise.all([
+    rm(path4.join(cacheDir, "package-lock.json"), { force: true }),
+    rm(path4.join(cacheDir, "node_modules", ".package-lock.json"), { force: true })
+  ]);
+}
+function packageNameFromSpec(packageSpec) {
+  if (!packageSpec.startsWith("@")) {
+    const versionSeparator2 = packageSpec.indexOf("@");
+    return versionSeparator2 === -1 ? packageSpec : packageSpec.slice(0, versionSeparator2);
+  }
+  const versionSeparator = packageSpec.indexOf("@", 1);
+  return versionSeparator === -1 ? packageSpec : packageSpec.slice(0, versionSeparator);
+}
+function normalizeOptionalDependencyVersion(versionRange) {
+  const trimmed = versionRange?.trim();
+  if (!trimmed) return null;
+  const exactVersion = /^[~^]\s*([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)$/.exec(trimmed);
+  return exactVersion?.[1] ?? trimmed;
+}
+function runtimePostgresPlatformSegment(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+function runtimePostgresExecutableName(baseName) {
+  return process.platform === "win32" ? `${baseName}.exe` : baseName;
+}
+async function assertRuntimePostgresBinDirComplete(cacheDir, binDir) {
+  const requiredBinaries = ["initdb", "pg_ctl", "postgres"];
+  const missing = [];
+  for (const binary of requiredBinaries) {
+    const binaryPath = path4.join(binDir, runtimePostgresExecutableName(binary));
+    try {
+      await stat(binaryPath);
+    } catch {
+      missing.push(binaryPath);
+    }
+  }
+  if (missing.length > 0) {
+    throw new RuntimeInstallError(
+      `${RUDDER_POSTGRES_BIN_DIR_ENV} must contain PostgreSQL 18.4 initdb, pg_ctl, and postgres binaries; missing ${missing.join(", ")}`,
+      { cacheDir, command: "validate PostgreSQL 18.4 runtime payload", output: "" }
+    );
+  }
+}
+async function isRuntimePostgresPayloadUsable(cacheDir, binDir) {
+  try {
+    await assertRuntimePostgresBinDirComplete(cacheDir, binDir);
+    const postgresBinary = path4.join(binDir, runtimePostgresExecutableName("postgres"));
+    const result = execFileSync(postgresBinary, ["--version"], { encoding: "utf8" });
+    return /\bPostgreSQL\)?\s+18\.4\b/i.test(result);
+  } catch {
+    return false;
+  }
+}
+async function stageRuntimePostgresPayload(cacheDir, enabled) {
+  const targetRuntimeDir = path4.join(cacheDir, RUNTIME_POSTGRES_PAYLOAD_DIR);
+  const targetBinDir = resolveRuntimePostgresPayloadBinDir(cacheDir);
+  if (await isRuntimePostgresPayloadUsable(cacheDir, targetBinDir)) {
+    return { output: "", binDir: targetBinDir };
+  }
+  if (!enabled) return { output: "" };
+  const sourceBinDir = process.env[RUDDER_POSTGRES_BIN_DIR_ENV]?.trim();
+  if (!sourceBinDir) return { output: "" };
+  const resolvedSourceBinDir = path4.resolve(sourceBinDir);
+  await assertRuntimePostgresBinDirComplete(cacheDir, resolvedSourceBinDir);
+  const postgresBinary = path4.join(resolvedSourceBinDir, runtimePostgresExecutableName("postgres"));
+  const result = execFileSync(postgresBinary, ["--version"], { encoding: "utf8" });
+  if (!/\bPostgreSQL\)?\s+18\.4\b/i.test(result)) {
+    throw new RuntimeInstallError(
+      `${RUDDER_POSTGRES_BIN_DIR_ENV} must contain PostgreSQL 18.4 production binaries; got ${result.trim() || "unknown version"}`,
+      { cacheDir, command: `${postgresBinary} --version`, output: result }
+    );
+  }
+  await rm(targetRuntimeDir, { recursive: true, force: true });
+  await mkdir(path4.dirname(targetBinDir), { recursive: true });
+  await cp(resolvedSourceBinDir, targetBinDir, { recursive: true });
+  return { output: `staged PostgreSQL 18.4 runtime payload at ${targetBinDir}`, binDir: targetBinDir };
+}
 function isVersionNotFoundError(output) {
   const normalized = output.toLowerCase();
   return normalized.includes("enoent") || normalized.includes("etarget") || normalized.includes("no matching version found");
@@ -3928,19 +4202,34 @@ function parseRuntimeVersion(version) {
     canaryNumber: canaryMatch ? Number(canaryMatch[1]) : null
   };
 }
-var RUNTIME_NPM_PACKAGE_NAME, RUNTIME_METADATA_FILE, DEFAULT_RUNTIME_CACHE_MAX_ENTRIES, DEFAULT_RUNTIME_CACHE_MAX_AGE_MS, DEFAULT_RUNTIME_CACHE_MAX_BYTES, DEFAULT_RUNTIME_CACHE_KEEP_PREVIOUS, RUNTIME_NPM_INSTALL_FLAGS, EMBEDDED_POSTGRES_PACKAGE_NAME, RuntimeInstallError;
+var RUNTIME_NPM_PACKAGE_NAME, NPM_PUBLIC_REGISTRY_URL, RUNTIME_METADATA_FILE, RUNTIME_POSTGRES_PAYLOAD_DIR, DEFAULT_RUNTIME_CACHE_MAX_ENTRIES, DEFAULT_RUNTIME_CACHE_MAX_AGE_MS, DEFAULT_RUNTIME_CACHE_MAX_BYTES, DEFAULT_RUNTIME_CACHE_KEEP_PREVIOUS, RUNTIME_NPM_INSTALL_FLAGS, RUNTIME_NPM_PACK_FLAGS, EMBEDDED_POSTGRES_PACKAGE_NAME, RUDDER_POSTGRES_BIN_DIR_ENV, RUNTIME_CACHE_PACKAGE_JSON, NPM_PLATFORM_REPAIR_ENV, RuntimeInstallError;
 var init_install = __esm({
   "src/runtime/install.ts"() {
     "use strict";
     init_home();
     RUNTIME_NPM_PACKAGE_NAME = "@rudderhq/server";
+    NPM_PUBLIC_REGISTRY_URL = "https://registry.npmjs.org";
     RUNTIME_METADATA_FILE = "runtime.json";
+    RUNTIME_POSTGRES_PAYLOAD_DIR = "postgres-18.4";
     DEFAULT_RUNTIME_CACHE_MAX_ENTRIES = 2;
     DEFAULT_RUNTIME_CACHE_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1e3;
     DEFAULT_RUNTIME_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
     DEFAULT_RUNTIME_CACHE_KEEP_PREVIOUS = 0;
     RUNTIME_NPM_INSTALL_FLAGS = ["--omit=dev", "--include=optional", "--no-audit", "--no-fund"];
+    RUNTIME_NPM_PACK_FLAGS = ["--registry", NPM_PUBLIC_REGISTRY_URL, "--silent"];
     EMBEDDED_POSTGRES_PACKAGE_NAME = "embedded-postgres";
+    RUDDER_POSTGRES_BIN_DIR_ENV = "RUDDER_POSTGRES_BIN_DIR";
+    RUNTIME_CACHE_PACKAGE_JSON = {
+      name: "rudder-runtime-cache",
+      version: "0.0.0",
+      private: true,
+      type: "module"
+    };
+    NPM_PLATFORM_REPAIR_ENV = {
+      npm_config_registry: NPM_PUBLIC_REGISTRY_URL,
+      npm_config_update_notifier: "false",
+      NO_UPDATE_NOTIFIER: "1"
+    };
     RuntimeInstallError = class extends Error {
       cacheDir;
       command;
@@ -3991,9 +4280,15 @@ async function loadServerRuntimeModule(options) {
   }
   const installOptions = {
     version: options.version,
-    homeDir: options.homeDir
+    homeDir: options.homeDir,
+    preparePostgresPayload: true
   };
   const runtime = await ensureRuntimeInstalled(installOptions);
+  if (!process.env[RUDDER_POSTGRES_BIN_DIR_ENV2]?.trim()) {
+    if (runtime.postgresPayloadBinDir && fs3.existsSync(runtime.postgresPayloadBinDir)) {
+      process.env[RUDDER_POSTGRES_BIN_DIR_ENV2] = runtime.postgresPayloadBinDir;
+    }
+  }
   options.onRuntimeInstalled?.(runtime);
   return await importRuntimeServerModule(runtime.cacheDir);
 }
@@ -4016,10 +4311,12 @@ async function startServerFromModule(mod) {
     takeoverOnVersionMismatch: true
   });
 }
+var RUDDER_POSTGRES_BIN_DIR_ENV2;
 var init_server_entry = __esm({
   "src/runtime/server-entry.ts"() {
     "use strict";
     init_install();
+    RUDDER_POSTGRES_BIN_DIR_ENV2 = "RUDDER_POSTGRES_BIN_DIR";
   }
 });
 
@@ -5622,7 +5919,7 @@ var init_doctor = __esm({
 });
 
 // src/install.ts
-import { execFileSync, spawnSync as spawnSync2 } from "node:child_process";
+import { execFileSync as execFileSync2, spawnSync as spawnSync2 } from "node:child_process";
 function normalizePath(value) {
   return (value ?? "").replaceAll("\\", "/").toLowerCase();
 }
@@ -5651,10 +5948,10 @@ function isTransientBinaryPath(candidatePath) {
   const normalized = normalizePath(candidatePath);
   return normalized.includes("/_npx/");
 }
-function hasGlobalInstalledPackage(packageName, execFileSyncImpl = execFileSync) {
+function hasGlobalInstalledPackage(packageName, execFileSyncImpl = execFileSync2) {
   return getGlobalInstalledPackageVersion(packageName, execFileSyncImpl) !== null;
 }
-function getGlobalInstalledPackageVersion(packageName, execFileSyncImpl = execFileSync) {
+function getGlobalInstalledPackageVersion(packageName, execFileSyncImpl = execFileSync2) {
   try {
     const output = execFileSyncImpl(
       process.platform === "win32" ? "npm.cmd" : "npm",
@@ -5670,7 +5967,7 @@ function getGlobalInstalledPackageVersion(packageName, execFileSyncImpl = execFi
     return null;
   }
 }
-function hasPersistentBinaryOnPath(execFileSyncImpl = execFileSync) {
+function hasPersistentBinaryOnPath(execFileSyncImpl = execFileSync2) {
   const { command, args } = resolveCommandLookupExecutable();
   try {
     const output = execFileSyncImpl(command, args, {
@@ -5685,7 +5982,7 @@ function hasPersistentBinaryOnPath(execFileSyncImpl = execFileSync) {
 }
 function detectPersistentCliState(options = {}) {
   const env = options.env ?? process.env;
-  const execFileSyncImpl = options.execFileSyncImpl ?? execFileSync;
+  const execFileSyncImpl = options.execFileSyncImpl ?? execFileSync2;
   const installSpec = resolvePersistentCliInstallSpec(env);
   const usingNpx = isLikelyNpxExecutionContext(options.entryPath ?? process.argv[1], env);
   if (!usingNpx) {
@@ -7270,6 +7567,15 @@ function isMaintainerOnlySkillTarget(candidate) {
   const normalized = normalizePathSlashes(candidate);
   return normalized.includes("/server/resources/bundled-skills/") || normalized.includes("/.agents/skills/");
 }
+function parseObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function asString(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
 
 // ../packages/agent-runtime-utils/dist/server-utils.prompts.js
 var RUDDER_AGENT_OPERATING_CONTRACT = [
@@ -7293,7 +7599,7 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "- `library:projects/<project-key>/...` is the Rudder product locator for those files, not the Markdown link syntax and not a reason to route ordinary local edits through the CLI.",
   '- When you create or update a durable Library file, always include a user-visible Markdown link to that file in your final chat reply or issue comment. Use `rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>" --json` and paste the returned `markdownLink`; do not pass the absolute `$RUDDER_PROJECT_LIBRARY_ROOT/...` path to `ref`, and do not hand-write `library-entry://...` or `library-file://...` links.',
   '- If `$RUDDER_PROJECT_LIBRARY_ROOT` is unset or inaccessible, use `rudder library file get/put "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>"` as the remote or restricted runtime fallback.',
-  "- Use `/tmp` only for transient scratch files and temporary verification files; do not put durable work product there.",
+  "- Use `$RUDDER_RUNTIME_TMPDIR` for transient scratch files and temporary verification files when it is set; otherwise use `/tmp`. Do not put durable work product there.",
   "- Local trusted runtimes may expose the host operator home as `$RUDDER_OPERATOR_HOME`; use it only when a local skill or script intentionally needs operator-owned desktop app or CLI state. Do not replace `$HOME` with it.",
   "",
   "When you create or copy a skill under `$AGENT_HOME/skills/<slug>/`, check the agent's Skills snapshot before claiming it will load in future runs. If it is installed but not enabled, say exactly that future runs will not load it until enabled, and offer to enable it with `rudder agent skills enable <agent-id> <selection-ref>` when you have permission.",
@@ -7340,16 +7646,16 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
 var RUDDER_AGENT_HEARTBEAT_INSTRUCTION = [
   "# Rudder Heartbeat Instruction",
   "",
-  "This section is injected by Rudder for heartbeat scene runs. It is the platform-owned timed-wakeup pipeline.",
+  "This section is injected by Rudder only for heartbeat scene runs. It is the platform-owned heartbeat/self-check pipeline.",
   "",
   "## Heartbeat Pipeline",
   "",
   "1. Identify yourself and inspect wake context, including `RUDDER_TASK_ID`, `RUDDER_WAKE_REASON`, `RUDDER_WAKE_COMMENT_ID`, and `RUDDER_APPROVAL_ID` when present.",
   "2. Local Planning Check:",
   "   ",
-  "   1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under \"## Today's Plan\". You need to clearly know your work plan for today, and work according to the plan.",
-  "   2. Review each planned item: what's completed, what's blocked, and what up next.",
-  "   3. Record progress updates in the daily notes.",
+  "- Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under \"## Today's Plan\". You need to clearly know your work plan for today, and work according to the plan.",
+  "- Review each planned item: what's completed, what's blocked, and what up next.",
+  "- Record progress updates in the daily notes.",
   "   ",
   "3.Then handle approval follow-up: read the approval and linked issues, then close resolved work or comment on what remains.",
   "4. Inspect your Rudder inbox. Prioritize reviewer rows in `in_review` or `blocked`, then assignee `in_progress`, then assignee `todo`. Do not look for unassigned work.",
@@ -7357,8 +7663,8 @@ var RUDDER_AGENT_HEARTBEAT_INSTRUCTION = [
   "6. Checkout before doing assignee task work. A `409` means another agent owns the task; do not retry it.",
   "7. Load compact issue context, do one bounded useful chunk, and preserve evidence.",
   "8. Before exiting active work, leave exactly one durable signal: progress, done, blocked, explicit handoff, or structured review decision.",
-  "9. Treat passive follow-up as close-out governance, not a fresh assignment.",
-  "10. Treat review close-out follow-up as review governance; free-form accept/reject text is not a durable decision.",
+  "9. Treat passive follow-up as issue follow-up, not a fresh assignment.",
+  "10. Treat review close-out follow-up as review follow-up; free-form accept/reject text is not a durable decision.",
   "",
   "Use the Rudder control-plane interface available in this runtime. CLI-capable runtimes should use the bundled `rudder` skill for command details, Library handoff rules, organization-skill workflow, and control-plane best practices. HTTP compatibility runtimes should follow the explicit HTTP workflow in their wake text; that workflow overrides CLI command guidance."
 ].join("\n");
@@ -7381,25 +7687,48 @@ async function resolveRudderSkillsDir(moduleDir, additionalCandidates = []) {
   return null;
 }
 async function removeMaintainerOnlySkillSymlinks(skillsHome, allowedSkillNames) {
+  return removeUnselectedRudderSkillSymlinks(skillsHome, allowedSkillNames);
+}
+async function readRudderMaterializedSkillSource(target) {
+  const manifestPath = path9.join(target, ".rudder", "materialized-skill.json");
+  const raw = await fs6.readFile(manifestPath, "utf8").catch(() => null);
+  if (!raw)
+    return null;
+  try {
+    const parsed = parseObject(JSON.parse(raw));
+    const sourcePath = asString(parsed.sourcePath, "").trim();
+    return sourcePath.length > 0 ? path9.resolve(sourcePath) : null;
+  } catch {
+    return null;
+  }
+}
+async function removeUnselectedRudderSkillSymlinks(skillsHome, allowedSkillNames, knownSkillSources = []) {
   const allowed = new Set(Array.from(allowedSkillNames));
+  const knownSources = new Set(Array.from(knownSkillSources).map((value) => value.trim()).filter(Boolean).map((value) => path9.resolve(value)));
   try {
     const entries = await fs6.readdir(skillsHome, { withFileTypes: true });
     const removed = [];
     for (const entry of entries) {
-      if (allowed.has(entry.name))
-        continue;
       const target = path9.join(skillsHome, entry.name);
       const existing = await fs6.lstat(target).catch(() => null);
-      if (!existing?.isSymbolicLink())
+      if (!existing)
         continue;
-      const linkedPath = await fs6.readlink(target).catch(() => null);
-      if (!linkedPath)
+      let isRudderManagedSkill = false;
+      if (existing.isSymbolicLink()) {
+        const linkedPath = await fs6.readlink(target).catch(() => null);
+        if (!linkedPath)
+          continue;
+        const resolvedLinkedPath = path9.isAbsolute(linkedPath) ? linkedPath : path9.resolve(path9.dirname(target), linkedPath);
+        isRudderManagedSkill = knownSources.has(path9.resolve(resolvedLinkedPath)) || isMaintainerOnlySkillTarget(linkedPath) || isMaintainerOnlySkillTarget(resolvedLinkedPath);
+      } else if (existing.isDirectory()) {
+        const materializedSource = await readRudderMaterializedSkillSource(target);
+        isRudderManagedSkill = materializedSource !== null && knownSources.has(materializedSource);
+      }
+      if (!isRudderManagedSkill)
         continue;
-      const resolvedLinkedPath = path9.isAbsolute(linkedPath) ? linkedPath : path9.resolve(path9.dirname(target), linkedPath);
-      if (!isMaintainerOnlySkillTarget(linkedPath) && !isMaintainerOnlySkillTarget(resolvedLinkedPath)) {
+      if (allowed.has(entry.name))
         continue;
-      }
-      await fs6.unlink(target);
+      await fs6.rm(target, { recursive: true, force: true });
       removed.push(entry.name);
     }
     return removed;
@@ -13668,7 +13997,7 @@ import * as p15 from "@clack/prompts";
 import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { createWriteStream, constants as fsConstants, mkdirSync, readFileSync as readFileSync2 } from "node:fs";
-import { access, chmod, copyFile, cp, mkdir as mkdir3, mkdtemp, readdir as readdir3, readFile as readFile6, rm as rm2, stat as stat4, utimes, writeFile as writeFile3 } from "node:fs/promises";
+import { access, chmod, copyFile, cp as cp2, mkdir as mkdir3, mkdtemp, readdir as readdir3, readFile as readFile6, rm as rm2, stat as stat4, utimes, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path21 from "node:path";
 import { Readable, Transform } from "node:stream";
@@ -13963,6 +14292,9 @@ function resolveDesktopReleaseTag(version) {
 function isExactRuntimePackageSpec(version, packageSpec) {
   return version !== "latest" && packageSpec === resolveRuntimePackageSpec(version);
 }
+function runtimeSupportsDesktopShellAssets(version, runtime) {
+  return isExactRuntimePackageSpec(version, runtime.packageSpec) && Boolean(runtime.postgresPayloadBinDir);
+}
 function resolveDesktopAssetTarget(platform = process.platform, arch = process.arch) {
   if (platform === "darwin") {
     if (arch !== "x64" && arch !== "arm64") {
@@ -14843,7 +15175,7 @@ async function copyPortableAppBundle(sourcePath, destinationPath) {
     if (isSuccessfulRobocopyExitCode(result.status)) return;
     throw new Error(formatCommandFailure(command.command, command.args, result.stdout, result.stderr));
   }
-  await cp(sourcePath, destinationPath, { recursive: true, verbatimSymlinks: true });
+  await cp2(sourcePath, destinationPath, { recursive: true, verbatimSymlinks: true });
 }
 async function removeMacQuarantine(paths, target) {
   if (target.platform !== "macos") return;
@@ -14958,7 +15290,8 @@ async function runStartPhase(message, successMessage, task, progressPhase) {
 }
 async function startCommand(opts) {
   const installCli = opts.cli !== false;
-  const installDesktop = opts.desktop !== false;
+  const serverOnly = opts.serverOnly === true;
+  const installDesktop = !serverOnly && opts.desktop !== false;
   const installRuntime = opts.runtime !== false;
   const repo = opts.repo?.trim() || DEFAULT_DESKTOP_RELEASE_REPO;
   const version = opts.targetVersion?.trim() || opts.version?.trim() || resolveCurrentCliVersion();
@@ -14971,9 +15304,9 @@ async function startCommand(opts) {
     });
   }
   if (!installCli && !installDesktop && !installRuntime) {
-    throw new Error("Nothing to start. Remove --no-cli, --no-runtime, or --no-desktop.");
+    throw new Error("Nothing to start. Remove --no-cli, --no-runtime, --no-desktop, or --server-only.");
   }
-  p15.intro(pc15.bgCyan(pc15.black(" rudder start ")));
+  p15.intro(pc15.bgCyan(pc15.black(serverOnly ? " rudder start --server-only " : " rudder start ")));
   if (opts.versionCheck !== false) {
     const updateNotice = await getCliUpdateNotice(version);
     if (updateNotice) p15.log.warn(updateNotice);
@@ -14986,11 +15319,14 @@ async function startCommand(opts) {
       const spinner3 = p15.spinner();
       spinner3.start("Installing or reusing Rudder runtime...");
       try {
-        const runtime = await ensureRuntimeInstalled({ version });
-        runtimeSupportsShellAssets = isExactRuntimePackageSpec(version, runtime.packageSpec);
+        const runtime = await ensureRuntimeInstalled({ version, preparePostgresPayload: true });
+        runtimeSupportsShellAssets = runtimeSupportsDesktopShellAssets(version, runtime);
         spinner3.stop(
           runtime.status === "hit" ? `Rudder runtime cache hit at ${pc15.cyan(runtime.cacheDir)}.` : `Rudder runtime installed at ${pc15.cyan(runtime.cacheDir)}.`
         );
+        if (!runtime.postgresPayloadBinDir && installDesktop) {
+          p15.log.warn("Rudder runtime cache has no PostgreSQL 18.4 payload; the full portable Desktop asset will be used.");
+        }
         if (!runtimeSupportsShellAssets && installDesktop) {
           p15.log.warn("Rudder runtime did not resolve to the exact Desktop version; the full portable Desktop asset will be used.");
         }
@@ -15198,6 +15534,9 @@ async function startCommand(opts) {
         );
       }
     });
+  } else if (serverOnly) {
+    p15.log.step("Server-only install");
+    p15.log.message("Desktop app installation was skipped. Start the server with `rudder run` and open the printed local URL in a browser.");
   }
   p15.outro(pc15.green("Rudder start complete."));
 }
@@ -15268,7 +15607,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-runtime", "Skip Rudder runtime installation").option("--no-desktop", "Skip desktop app installation").option("--version <version>", "Rudder version to start (default: current CLI version)").option("--target-version <version>", "Rudder version to start; avoids the root CLI version flag").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("--wait-for-active-runs", "Wait for active Rudder runs to finish before replacing Desktop", false).option("--desktop-progress-json", "Emit newline-delimited Desktop update progress events").option("--desktop-wait-for-apply", "Wait for an apply signal after downloading and verifying the Desktop update", false).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("--server-only", "Prepare the Rudder server runtime and persistent CLI without installing Desktop").option("--no-cli", "Skip persistent CLI installation").option("--no-runtime", "Skip Rudder runtime installation").option("--no-desktop", "Skip desktop app installation").option("--version <version>", "Rudder version to start (default: current CLI version)").option("--target-version <version>", "Rudder version to start; avoids the root CLI version flag").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("--wait-for-active-runs", "Wait for active Rudder runs to finish before replacing Desktop", false).option("--desktop-progress-json", "Emit newline-delimited Desktop update progress events").option("--desktop-wait-for-apply", "Wait for an apply signal after downloading and verifying the Desktop update", false).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);