@pushpalsdev/cli 1.0.1 → 1.0.3

package/README.md

@@ -25,10 +25,18 @@ pushpals
 The CLI hard-fails if:
 
 - current directory is not a git repository
-- LocalBuddy is unavailable
 - LocalBuddy is attached to a different repo root
 - Bun runtime is not installed (for npm-installed entrypoint execution)
 
+Behavior:
+
+- If LocalBuddy is unavailable, CLI auto-start bootstraps embedded
+  `server + localbuddy + remotebuddy + source_control_manager`.
+- Auto-start does not clone the PushPals repo; it downloads release-tagged runtime binaries
+  and prompt/config assets into `~/.pushpals/runtime`.
+- Override runtime tag with `pushpals --runtime-tag vX.Y.Z`.
+- Disable auto-start with `pushpals --no-auto-start`.
+
 ## No npm/Bun install
 
 Download native binaries from GitHub Releases:

package/bin/pushpals.cjs

@@ -2,11 +2,21 @@
 "use strict";
 
 const { spawn, spawnSync } = require("node:child_process");
-const { existsSync } = require("node:fs");
+const { existsSync, readFileSync } = require("node:fs");
 const { resolve } = require("node:path");
 
 const bundledCliPath = resolve(__dirname, "..", "dist", "pushpals-cli.js");
+const packageJsonPath = resolve(__dirname, "..", "package.json");
 const releaseUrl = "https://github.com/PushPalsDev/pushpals/releases";
+let packageVersion = "";
+if (existsSync(packageJsonPath)) {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    packageVersion = String(parsed?.version ?? "").trim();
+  } catch {
+    packageVersion = "";
+  }
+}
 
 function fail(lines) {
   for (const line of lines) {
@@ -41,10 +51,15 @@ if (!hasBunRuntime()) {
 }
 
 function spawnBunCli() {
+  const childEnv = {
+    ...process.env,
+    PUSHPALS_CLI_PACKAGE_VERSION: packageVersion || process.env.PUSHPALS_CLI_PACKAGE_VERSION || "",
+  };
+
   if (process.platform !== "win32") {
     return spawn("bun", [bundledCliPath, ...process.argv.slice(2)], {
       stdio: "inherit",
-      env: process.env,
+      env: childEnv,
     });
   }
 
@@ -57,7 +72,7 @@ function spawnBunCli() {
   return spawn(commandLine, {
     shell: true,
     stdio: "inherit",
-    env: process.env,
+    env: childEnv,
   });
 }
 

package/dist/pushpals-cli.js

@@ -2,8 +2,8 @@
 // @bun
 
 // ../../scripts/pushpals-cli.ts
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { dirname, resolve as resolve2 } from "path";
+import { chmodSync, cpSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { dirname, join as join2, resolve as resolve2 } from "path";
 import { createInterface } from "readline";
 
 // ../shared/src/config.ts
@@ -250,10 +250,12 @@ function resolveLlmConfig(serviceNode, envPrefix, defaults, globalSessionId) {
   };
 }
 function loadPushPalsConfig(options = {}) {
-  const projectRoot = resolve(options.projectRoot ?? PROJECT_ROOT);
-  const configDir = resolveRuntimeConfigDir(projectRoot, options.configDir);
+  const projectRootOverride = firstNonEmpty(options.projectRoot, process.env.PUSHPALS_PROJECT_ROOT_OVERRIDE, PROJECT_ROOT);
+  const projectRoot = resolve(projectRootOverride);
+  const configDirOverride = firstNonEmpty(options.configDir, process.env.PUSHPALS_CONFIG_DIR_OVERRIDE, "");
+  const configDir = resolveRuntimeConfigDir(projectRoot, configDirOverride);
   const legacyConfigDir = resolvePathFromRoot(projectRoot, LEGACY_CONFIG_DIR);
-  const fallbackConfigDir = !options.configDir && configDir !== legacyConfigDir ? legacyConfigDir : "";
+  const fallbackConfigDir = !configDirOverride && configDir !== legacyConfigDir ? legacyConfigDir : "";
   const cacheKey = `${projectRoot}::${configDir}::${process.env.PUSHPALS_PROFILE ?? ""}`;
   if (!options.reload && cachedConfig && cachedConfigKey === cacheKey) {
     return cachedConfig;
@@ -743,6 +745,16 @@ var MONITOR_SCAN_PORTS = 32;
 var HTTP_TIMEOUT_MS = 2500;
 var LOCALBUDDY_TIMEOUT_MS = 4000;
 var SSE_RECONNECT_MS = 1500;
+var DEFAULT_RUNTIME_BOOT_TIMEOUT_MS = 90000;
+var DEFAULT_RUNTIME_BOOT_POLL_MS = 1000;
+var GITHUB_OWNER = "PushPalsDev";
+var GITHUB_REPO = "pushpals";
+var GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}`;
+var GITHUB_RELEASE_URL = `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}/releases/download`;
+var GITHUB_HEADERS = {
+  Accept: "application/vnd.github+json",
+  "User-Agent": "pushpals-cli"
+};
 var stateVersion = 1;
 function printUsage() {
   console.log("PushPals CLI");
@@ -755,6 +767,9 @@ function printUsage() {
   console.log("  --local-agent-url <url> Override LocalBuddy URL");
   console.log("  --session-id <id>      Override session ID");
   console.log("  --hub-url <url>        Override monitoring hub URL");
+  console.log("  --runtime-root <path>  Override embedded runtime directory for auto-start");
+  console.log("  --runtime-tag <tag>    Override runtime release tag (e.g. v1.0.2)");
+  console.log("  --no-auto-start        Disable runtime auto-start when LocalBuddy is down");
   console.log("  --no-stream            Disable live session event stream");
   console.log("  -h, --help             Show this help");
   console.log("");
@@ -766,10 +781,11 @@ function printUsage() {
   console.log("");
   console.log("Notes:");
   console.log("  - Must be run from inside a git repository.");
-  console.log("  - LocalBuddy must be running and attached to the same repo root.");
+  console.log("  - Auto-start can bootstrap server/localbuddy/remotebuddy/source_control_manager.");
+  console.log("  - LocalBuddy must be attached to the same repo root.");
 }
 function parseArgs(argv) {
-  const options = { noStream: false };
+  const options = { noAutoStart: false, noStream: false };
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "-h" || arg === "--help") {
@@ -780,6 +796,10 @@ function parseArgs(argv) {
       options.noStream = true;
       continue;
     }
+    if (arg === "--no-auto-start") {
+      options.noAutoStart = true;
+      continue;
+    }
     if (arg === "--server-url") {
       options.serverUrl = argv[++i];
       continue;
@@ -796,6 +816,14 @@ function parseArgs(argv) {
       options.monitoringHubUrl = argv[++i];
       continue;
     }
+    if (arg === "--runtime-root") {
+      options.runtimeRoot = argv[++i];
+      continue;
+    }
+    if (arg === "--runtime-tag") {
+      options.runtimeTag = argv[++i];
+      continue;
+    }
     console.error(`[pushpals] Unknown argument: ${arg}`);
     printUsage();
     process.exit(2);
@@ -841,6 +869,202 @@ async function resolveCurrentGitRepoRoot(cwd) {
     return null;
   return resolve2(root.stdout);
 }
+function resolveDefaultRuntimeRoot() {
+  const home = process.env.USERPROFILE || process.env.HOME || process.cwd();
+  return resolve2(home, ".pushpals", "runtime");
+}
+function parseSemverFromPackageVersion(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw)
+    return "";
+  const match = raw.match(/^\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.-]+)?$/);
+  return match ? raw : "";
+}
+function resolveRuntimePlatformKey() {
+  if (process.platform === "win32")
+    return "windows-x64";
+  if (process.platform === "linux")
+    return "linux-x64";
+  if (process.platform === "darwin") {
+    return process.arch === "arm64" ? "macos-arm64" : "macos-x64";
+  }
+  throw new Error(`Unsupported platform for embedded runtime binaries: ${process.platform}/${process.arch}`);
+}
+async function fetchLatestReleaseTag() {
+  const response = await fetchWithTimeout(`${GITHUB_API_URL}/releases/latest`, { headers: GITHUB_HEADERS }, 20000);
+  if (!response.ok) {
+    throw new Error(`Failed to resolve latest release tag (HTTP ${response.status})`);
+  }
+  const payload = await response.json();
+  const tagName = String(payload.tag_name ?? "").trim();
+  if (!tagName)
+    throw new Error("Latest release payload did not include tag_name");
+  return tagName;
+}
+async function resolveRuntimeReleaseTag(explicitTag) {
+  const fromArg = String(explicitTag ?? "").trim();
+  if (fromArg)
+    return fromArg;
+  const fromEnv = String(process.env.PUSHPALS_RUNTIME_TAG ?? "").trim();
+  if (fromEnv)
+    return fromEnv;
+  const packageVersion = parseSemverFromPackageVersion(process.env.PUSHPALS_CLI_PACKAGE_VERSION);
+  if (packageVersion)
+    return `v${packageVersion}`;
+  return await fetchLatestReleaseTag();
+}
+function writeTextFileIfMissing(pathValue, text) {
+  if (existsSync2(pathValue))
+    return;
+  mkdirSync(dirname(pathValue), { recursive: true });
+  writeFileSync(pathValue, text, "utf8");
+}
+function copyBundledRuntimeAssets(runtimeRoot) {
+  const bundledRoot = resolve2(import.meta.dir, "..", "runtime");
+  if (!existsSync2(bundledRoot))
+    return false;
+  cpSync(bundledRoot, runtimeRoot, { recursive: true, force: true });
+  return true;
+}
+async function fetchTextFromUrl(url, timeoutMs = 20000) {
+  const response = await fetchWithTimeout(url, { headers: GITHUB_HEADERS }, timeoutMs);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} while fetching ${url}`);
+  }
+  return await response.text();
+}
+async function downloadRuntimeAssetsFromSourceTag(runtimeRoot, tag) {
+  const treeUrl = `${GITHUB_API_URL}/git/trees/${encodeURIComponent(tag)}?recursive=1`;
+  const treeResponse = await fetchWithTimeout(treeUrl, { headers: GITHUB_HEADERS }, 30000);
+  if (!treeResponse.ok) {
+    throw new Error(`Failed to fetch runtime source tree for ${tag} (HTTP ${treeResponse.status})`);
+  }
+  const treePayload = await treeResponse.json();
+  const paths = (treePayload.tree ?? []).filter((entry) => entry.type === "blob" && typeof entry.path === "string").map((entry) => String(entry.path)).filter((pathValue) => pathValue === ".env.example" || pathValue.startsWith("configs/") || pathValue.startsWith("prompts/"));
+  if (paths.length === 0) {
+    throw new Error(`Runtime source tree for ${tag} did not include prompts/config assets`);
+  }
+  const sorted = [...paths].sort((a, b) => a.localeCompare(b));
+  for (const pathValue of sorted) {
+    const rawUrl = `https://raw.githubusercontent.com/${GITHUB_OWNER}/${GITHUB_REPO}/${encodeURIComponent(tag)}/${pathValue}`;
+    const body = await fetchTextFromUrl(rawUrl, 20000);
+    const outPath = join2(runtimeRoot, pathValue);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, body, "utf8");
+  }
+}
+async function ensureRuntimeAssets(runtimeRoot, runtimeTag) {
+  const markerPath = join2(runtimeRoot, ".runtime-assets-tag");
+  const currentTag = existsSync2(markerPath) ? readFileSync2(markerPath, "utf8").trim() : "";
+  const hasAssets = existsSync2(join2(runtimeRoot, ".env.example")) && existsSync2(join2(runtimeRoot, "configs", "default.toml")) && existsSync2(join2(runtimeRoot, "prompts"));
+  if (!hasAssets || currentTag !== runtimeTag) {
+    const copied = copyBundledRuntimeAssets(runtimeRoot);
+    if (!copied) {
+      await downloadRuntimeAssetsFromSourceTag(runtimeRoot, runtimeTag);
+    }
+    writeFileSync(markerPath, `${runtimeTag}
+`, "utf8");
+  }
+  writeTextFileIfMissing(join2(runtimeRoot, ".env"), `# Local PushPals runtime environment
+`);
+  const localExamplePath = join2(runtimeRoot, "configs", "local.example.toml");
+  if (existsSync2(localExamplePath)) {
+    writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), readFileSync2(localExamplePath, "utf8"));
+  } else {
+    writeTextFileIfMissing(join2(runtimeRoot, "configs", "local.toml"), `# Local PushPals runtime overrides
+`);
+  }
+}
+function runtimeBinaryFilename(serviceName, platformKey) {
+  const serviceToken = serviceName === "source_control_manager" ? "source-control-manager" : serviceName;
+  const extension = platformKey.startsWith("windows-") ? ".exe" : "";
+  return `pushpals-runtime-${serviceToken}-${platformKey}${extension}`;
+}
+async function downloadBinaryAsset(tag, assetName, outPath) {
+  const url = `${GITHUB_RELEASE_URL}/${encodeURIComponent(tag)}/${assetName}`;
+  const response = await fetchWithTimeout(url, { headers: GITHUB_HEADERS }, 60000);
+  if (!response.ok) {
+    throw new Error(`Failed to download ${assetName} from ${tag} (HTTP ${response.status})`);
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  mkdirSync(dirname(outPath), { recursive: true });
+  await Bun.write(outPath, bytes);
+}
+async function ensureRuntimeBinaries(runtimeRoot, runtimeTag) {
+  const platformKey = resolveRuntimePlatformKey();
+  const binDir = join2(runtimeRoot, "bin", `${runtimeTag}-${platformKey}`);
+  mkdirSync(binDir, { recursive: true });
+  const runtimeBinaries = {
+    server: join2(binDir, runtimeBinaryFilename("server", platformKey)),
+    localbuddy: join2(binDir, runtimeBinaryFilename("localbuddy", platformKey)),
+    remotebuddy: join2(binDir, runtimeBinaryFilename("remotebuddy", platformKey)),
+    sourceControlManager: join2(binDir, runtimeBinaryFilename("source_control_manager", platformKey))
+  };
+  const requiredAssets = [
+    runtimeBinaries.server,
+    runtimeBinaries.localbuddy,
+    runtimeBinaries.remotebuddy,
+    runtimeBinaries.sourceControlManager
+  ];
+  for (const binaryPath of requiredAssets) {
+    if (existsSync2(binaryPath))
+      continue;
+    const assetName = binaryPath.split(/[\\/]/).pop() || "";
+    await downloadBinaryAsset(runtimeTag, assetName, binaryPath);
+  }
+  if (process.platform !== "win32") {
+    for (const binaryPath of requiredAssets) {
+      try {
+        chmodSync(binaryPath, 493);
+      } catch {}
+    }
+  }
+  return runtimeBinaries;
+}
+function spawnRuntimeService(name, command, cwd, env) {
+  const proc = Bun.spawn(command, {
+    cwd,
+    env,
+    stdout: "ignore",
+    stderr: "ignore"
+  });
+  const service = {
+    name,
+    proc,
+    exited: false,
+    exitCode: null
+  };
+  proc.exited.then((code) => {
+    service.exited = true;
+    service.exitCode = code;
+  });
+  return service;
+}
+function stopRuntimeServices(services) {
+  for (const service of services) {
+    try {
+      service.proc.kill();
+    } catch {}
+  }
+}
+async function probeServer(serverUrl) {
+  try {
+    const response = await fetchWithTimeout(`${serverUrl}/healthz`, {}, HTTP_TIMEOUT_MS);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function probeSourceControlManager(port) {
+  if (!Number.isFinite(port) || port <= 0)
+    return false;
+  try {
+    const response = await fetchWithTimeout(`http://127.0.0.1:${Math.floor(port)}/health`, {}, HTTP_TIMEOUT_MS);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
 async function fetchWithTimeout(url, init = {}, timeoutMs = HTTP_TIMEOUT_MS) {
   const controller = new AbortController;
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -868,6 +1092,64 @@ function authHeaders(authToken) {
 async function probeLocalBuddy(localAgentUrl, authToken) {
   return await fetchJsonWithTimeout(`${localAgentUrl}/healthz`, { headers: authHeaders(authToken) }, LOCALBUDDY_TIMEOUT_MS);
 }
+async function autoStartRuntimeServices(opts) {
+  const runtimeRoot = resolve2(opts.runtimeRoot || process.env.PUSHPALS_RUNTIME_ROOT || resolveDefaultRuntimeRoot());
+  const runtimeTag = await resolveRuntimeReleaseTag(opts.runtimeTag);
+  const runtimeBinaries = await ensureRuntimeBinaries(runtimeRoot, runtimeTag);
+  await ensureRuntimeAssets(runtimeRoot, runtimeTag);
+  console.log(`[pushpals] LocalBuddy unavailable. Auto-starting runtime for repo: ${opts.repoRoot}`);
+  console.log(`[pushpals] runtimeRoot=${runtimeRoot}`);
+  console.log(`[pushpals] runtimeTag=${runtimeTag}`);
+  const runtimeEnv = {
+    ...process.env,
+    PUSHPALS_REPO_ROOT_OVERRIDE: opts.repoRoot,
+    PUSHPALS_PROJECT_ROOT_OVERRIDE: opts.repoRoot,
+    PUSHPALS_CONFIG_DIR_OVERRIDE: join2(runtimeRoot, "configs"),
+    PUSHPALS_PROMPTS_ROOT_OVERRIDE: runtimeRoot
+  };
+  const services = [];
+  const serverHealthy = await probeServer(opts.serverUrl);
+  if (!serverHealthy) {
+    console.log("[pushpals] Starting embedded server...");
+    services.push(spawnRuntimeService("server", [runtimeBinaries.server], opts.repoRoot, runtimeEnv));
+  } else {
+    console.log("[pushpals] Server already healthy; skipping embedded server start.");
+  }
+  console.log("[pushpals] Starting embedded LocalBuddy...");
+  services.push(spawnRuntimeService("localbuddy", [runtimeBinaries.localbuddy], opts.repoRoot, runtimeEnv));
+  console.log("[pushpals] Starting embedded RemoteBuddy...");
+  services.push(spawnRuntimeService("remotebuddy", [runtimeBinaries.remotebuddy], opts.repoRoot, runtimeEnv));
+  const scmHealthy = await probeSourceControlManager(opts.sourceControlManagerPort);
+  if (!scmHealthy) {
+    console.log("[pushpals] Starting embedded SourceControlManager...");
+    services.push(spawnRuntimeService("source_control_manager", [runtimeBinaries.sourceControlManager, "--skip-clean-check"], opts.repoRoot, runtimeEnv));
+  } else {
+    console.log("[pushpals] SourceControlManager already healthy; skipping embedded start.");
+  }
+  const deadline = Date.now() + DEFAULT_RUNTIME_BOOT_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    for (let i = services.length - 1;i >= 0; i--) {
+      const service = services[i];
+      if (service.exited) {
+        if (service.name === "source_control_manager") {
+          console.warn(`[pushpals] Embedded ${service.name} exited during startup (code=${service.exitCode ?? "unknown"}); continuing without SCM.`);
+          services.splice(i, 1);
+          continue;
+        }
+        stopRuntimeServices(services);
+        throw new Error(`Embedded ${service.name} exited during startup (code=${service.exitCode ?? "unknown"})`);
+      }
+    }
+    const health = await probeLocalBuddy(opts.localAgentUrl, opts.authToken);
+    if (health?.ok) {
+      console.log("[pushpals] Embedded runtime is ready.");
+      return services;
+    }
+    await Bun.sleep(DEFAULT_RUNTIME_BOOT_POLL_MS);
+  }
+  stopRuntimeServices(services);
+  throw new Error(`Timed out waiting for LocalBuddy at ${opts.localAgentUrl} after ${DEFAULT_RUNTIME_BOOT_TIMEOUT_MS}ms`);
+}
 function readCliState(pathValue) {
   if (!existsSync2(pathValue))
     return {};
@@ -1129,18 +1411,48 @@ async function main() {
   const localAgentUrl = normalizeUrl(parsed.localAgentUrl ?? process.env.EXPO_PUBLIC_LOCAL_AGENT_URL, config.client.localAgentUrl);
   const sessionId = String(parsed.sessionId ?? process.env.PUSHPALS_SESSION_ID ?? config.sessionId).trim();
   const authToken = config.authToken;
-  const health = await probeLocalBuddy(localAgentUrl, authToken);
+  let autoStartedServices = [];
+  const stopAutoStartedServices = () => {
+    if (autoStartedServices.length === 0)
+      return;
+    stopRuntimeServices(autoStartedServices);
+    autoStartedServices = [];
+  };
+  let health = await probeLocalBuddy(localAgentUrl, authToken);
+  if (!health?.ok && !parsed.noAutoStart) {
+    try {
+      autoStartedServices = await autoStartRuntimeServices({
+        repoRoot,
+        serverUrl,
+        localAgentUrl,
+        sourceControlManagerPort: config.sourceControlManager.port,
+        authToken,
+        runtimeRoot: parsed.runtimeRoot,
+        runtimeTag: parsed.runtimeTag
+      });
+      health = await probeLocalBuddy(localAgentUrl, authToken);
+    } catch (err) {
+      console.error(`[pushpals] Auto-start failed: ${String(err)}`);
+      stopAutoStartedServices();
+    }
+  }
   if (!health?.ok) {
     console.error(`[pushpals] LocalBuddy is unavailable at ${localAgentUrl}.`);
-    console.error("[pushpals] Start the stack first, then rerun `pushpals`.");
+    if (parsed.noAutoStart) {
+      console.error("[pushpals] Auto-start is disabled (--no-auto-start).");
+    } else {
+      console.error("[pushpals] Auto-start could not bring LocalBuddy online.");
+    }
     process.exit(1);
   }
   const localBuddyRepo = health.repo ? resolve2(health.repo) : "";
   if (!localBuddyRepo) {
+    stopAutoStartedServices();
     console.error("[pushpals] LocalBuddy health response did not include repo path.");
     process.exit(1);
   }
   if (normalizePath(localBuddyRepo) !== normalizePath(repoRoot)) {
+    stopAutoStartedServices();
     console.error("[pushpals] Repo mismatch detected.");
     console.error(`[pushpals] currentRepo=${repoRoot}`);
     console.error(`[pushpals] localBuddyRepo=${localBuddyRepo}`);
@@ -1194,6 +1506,7 @@ ${line}
     streamAbort.abort();
     if (rl)
       rl.close();
+    stopAutoStartedServices();
   };
   process.once("SIGINT", requestStop);
   process.once("SIGTERM", requestStop);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushpalsdev/cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "PushPals terminal CLI for LocalBuddy -> RemoteBuddy orchestration",
   "license": "MIT",
   "repository": {