@pushpalsdev/cli 1.0.18 → 1.0.20

package/runtime/sandbox/packages/shared/src/localbuddy_runtime.ts

@@ -0,0 +1,314 @@
+import { existsSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
+
+export type LocalBuddyRuntimeAction = "start" | "stop" | "noop";
+export type LocalBuddyStartGateReason = "ready" | "backoff" | "retry_exhausted";
+
+export type LocalBuddyRuntimeSnapshot = {
+  localbuddy: {
+    enabled: boolean;
+    port: number;
+  };
+};
+
+export const DEFAULT_LOCALBUDDY_PORT = 3003;
+
+const DEFAULT_CONFIG_DIR = "configs";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+const FALSY = new Set(["0", "false", "no", "off"]);
+
+type LocalBuddyTomlSlice = {
+  profile?: string;
+  localbuddy?: {
+    enabled?: boolean;
+    port?: number;
+  };
+};
+
+export function parseLocalBuddyRuntimeSnapshot(raw: string): LocalBuddyRuntimeSnapshot {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("runtime config snapshot was not valid JSON");
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("runtime config snapshot must be a JSON object");
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const localbuddyValue = record.localbuddy;
+  if (!localbuddyValue || typeof localbuddyValue !== "object" || Array.isArray(localbuddyValue)) {
+    throw new Error("runtime config snapshot must include localbuddy");
+  }
+
+  const localbuddy = localbuddyValue as Record<string, unknown>;
+  const enabled = Boolean(localbuddy.enabled);
+  const port = Number.parseInt(String(localbuddy.port ?? DEFAULT_LOCALBUDDY_PORT), 10);
+
+  return {
+    localbuddy: {
+      enabled,
+      port:
+        Number.isFinite(port) && port >= 1 && port <= 65_535
+          ? port
+          : DEFAULT_LOCALBUDDY_PORT,
+    },
+  };
+}
+
+export function loadLocalBuddyRuntimeSnapshotFromFiles(
+  workspaceRoot: string,
+  env: Record<string, string | undefined> = process.env,
+): LocalBuddyRuntimeSnapshot {
+  const envFileValues = readEnvFile(resolve(workspaceRoot, ".env"));
+  const mergedEnv: Record<string, string | undefined> = {
+    ...env,
+    ...envFileValues,
+  };
+
+  const configDirOverride = firstNonEmpty(mergedEnv.PUSHPALS_CONFIG_DIR_OVERRIDE);
+  const configDir = resolveRuntimeConfigDir(workspaceRoot, configDirOverride);
+  const defaultToml = readRequiredTomlSlice(join(configDir, "default.toml"));
+  const preferredProfile = firstNonEmpty(mergedEnv.PUSHPALS_PROFILE, defaultToml.profile, "dev");
+  const profileToml = readTomlSlice(join(configDir, `${preferredProfile}.toml`));
+  const localExampleToml = readTomlSlice(join(configDir, "local.example.toml"));
+  const localToml = readTomlSlice(join(configDir, "local.toml"));
+
+  const mergedLocalbuddy = {
+    ...defaultToml.localbuddy,
+    ...profileToml.localbuddy,
+    ...localExampleToml.localbuddy,
+    ...localToml.localbuddy,
+  };
+
+  const enabled = parseBoolEnv(mergedEnv.LOCALBUDDY_ENABLED) ?? mergedLocalbuddy.enabled ?? false;
+  const port =
+    parseIntEnv(mergedEnv.LOCAL_AGENT_PORT) ?? mergedLocalbuddy.port ?? DEFAULT_LOCALBUDDY_PORT;
+
+  return {
+    localbuddy: {
+      enabled,
+      port:
+        Number.isFinite(port) && port >= 1 && port <= 65_535
+          ? Math.floor(port)
+          : DEFAULT_LOCALBUDDY_PORT,
+    },
+  };
+}
+
+export function resolveLocalBuddyRuntimeAction(
+  running: boolean,
+  enabled: boolean,
+): LocalBuddyRuntimeAction {
+  if (enabled && !running) return "start";
+  if (!enabled && running) return "stop";
+  return "noop";
+}
+
+export function computeLocalBuddyRestartBackoffMs(
+  consecutiveFailures: number,
+  baseMs = 5_000,
+  maxMs = 60_000,
+): number {
+  const safeFailures = Math.max(1, Math.floor(consecutiveFailures));
+  const multiplier = 2 ** Math.max(0, safeFailures - 1);
+  return Math.min(maxMs, baseMs * multiplier);
+}
+
+export function resolveLocalBuddyStartGate(args: {
+  nowMs: number;
+  retryAfterMs: number;
+  consecutiveFailures: number;
+  maxConsecutiveFailures: number;
+}): LocalBuddyStartGateReason {
+  if (args.consecutiveFailures >= args.maxConsecutiveFailures) {
+    return "retry_exhausted";
+  }
+  if (args.retryAfterMs > args.nowMs) {
+    return "backoff";
+  }
+  return "ready";
+}
+
+function firstNonEmpty(...values: Array<string | undefined>): string {
+  for (const value of values) {
+    const trimmed = String(value ?? "").trim();
+    if (trimmed) return trimmed;
+  }
+  return "";
+}
+
+function resolvePathFromRoot(workspaceRoot: string, value: string): string {
+  if (!value) return workspaceRoot;
+  if (isAbsolute(value)) return resolve(value);
+  return resolve(workspaceRoot, value);
+}
+
+function resolveRuntimeConfigDir(workspaceRoot: string, configuredDir?: string): string {
+  if (configuredDir && configuredDir.trim()) {
+    return resolvePathFromRoot(workspaceRoot, configuredDir);
+  }
+
+  return resolvePathFromRoot(workspaceRoot, DEFAULT_CONFIG_DIR);
+}
+
+function parseBoolEnv(value: string | undefined): boolean | undefined {
+  const text = String(value ?? "").trim().toLowerCase();
+  if (!text) return undefined;
+  if (TRUTHY.has(text)) return true;
+  if (FALSY.has(text)) return false;
+  return undefined;
+}
+
+function parseIntEnv(value: string | undefined): number | undefined {
+  const text = String(value ?? "").trim();
+  if (!text) return undefined;
+  const parsed = Number.parseInt(text, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function readTomlSlice(path: string): LocalBuddyTomlSlice {
+  if (existsSync(path)) return parseTomlSlice(path);
+  return {};
+}
+
+function readRequiredTomlSlice(path: string): LocalBuddyTomlSlice {
+  if (!existsSync(path)) {
+    throw new Error(`Missing required runtime config file: ${path}`);
+  }
+  return parseTomlSlice(path);
+}
+
+function parseTomlSlice(path: string): LocalBuddyTomlSlice {
+  const text = readFileSync(path, "utf8");
+  const result: LocalBuddyTomlSlice = {};
+  let currentSection = "";
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = stripTomlComment(rawLine).trim();
+    if (!line) continue;
+
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      currentSection = String(sectionMatch[1] ?? "").trim();
+      continue;
+    }
+
+    const entryMatch = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*(.+)$/);
+    if (!entryMatch) continue;
+
+    const key = String(entryMatch[1] ?? "").trim();
+    const value = parseTomlScalar(String(entryMatch[2] ?? "").trim());
+
+    if (!currentSection && key === "profile" && typeof value === "string") {
+      result.profile = value;
+      continue;
+    }
+
+    if (currentSection !== "localbuddy") continue;
+    if (key === "enabled" && typeof value === "boolean") {
+      result.localbuddy = { ...(result.localbuddy ?? {}), enabled: value };
+    } else if (key === "port" && typeof value === "number") {
+      result.localbuddy = { ...(result.localbuddy ?? {}), port: value };
+    }
+  }
+
+  return result;
+}
+
+function stripTomlComment(line: string): string {
+  let inQuote = false;
+  let quoteChar = "";
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if ((char === '"' || char === "'") && (i === 0 || line[i - 1] !== "\\")) {
+      if (!inQuote) {
+        inQuote = true;
+        quoteChar = char;
+      } else if (quoteChar === char) {
+        inQuote = false;
+        quoteChar = "";
+      }
+      continue;
+    }
+    if (char === "#" && !inQuote) {
+      return line.slice(0, i);
+    }
+  }
+  return line;
+}
+
+function parseTomlScalar(value: string): string | number | boolean | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (/^-?\d+$/.test(trimmed)) {
+    const parsed = Number.parseInt(trimmed, 10);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  const quoted = trimmed.match(/^"(.*)"$/) ?? trimmed.match(/^'(.*)'$/);
+  if (quoted) {
+    return quoted[1] ?? "";
+  }
+  return trimmed;
+}
+
+function readEnvFile(path: string): Record<string, string> {
+  if (!existsSync(path)) return {};
+  const text = readFileSync(path, "utf8");
+  const values: Record<string, string> = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const parsed = parseEnvAssignment(rawLine);
+    if (!parsed) continue;
+    values[parsed.key] = parsed.value;
+  }
+  return values;
+}
+
+function parseEnvAssignment(line: string): { key: string; value: string } | null {
+  const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+  if (!match) return null;
+  return {
+    key: match[1],
+    value: parseEnvValue(match[2] ?? ""),
+  };
+}
+
+function parseEnvValue(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  if (trimmed.startsWith("#")) return "";
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      return JSON.parse(trimmed) as string;
+    } catch {
+      return trimmed.slice(1, -1);
+    }
+  }
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+
+  let inQuote = false;
+  let quoteChar = "";
+  for (let i = 0; i < trimmed.length; i += 1) {
+    const char = trimmed[i];
+    if ((char === '"' || char === "'") && (i === 0 || trimmed[i - 1] !== "\\")) {
+      if (!inQuote) {
+        inQuote = true;
+        quoteChar = char;
+      } else if (quoteChar === char) {
+        inQuote = false;
+        quoteChar = "";
+      }
+      continue;
+    }
+    if (char === "#" && !inQuote) {
+      return trimmed.slice(0, i).trimEnd();
+    }
+  }
+  return trimmed;
+}

package/runtime/sandbox/packages/shared/src/prompts.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "fs";
+import { join, resolve } from "path";
+import { detectRepoRoot } from "./repo.js";
+
+const TEMPLATE_TOKEN = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+const promptTemplateCache = new Map<string, string>();
+const repoDocCache = new Map<string, string>();
+
+function resolvePromptPath(relativePath: string): string {
+  const promptRootOverride = String(process.env.PUSHPALS_PROMPTS_ROOT_OVERRIDE ?? "").trim();
+  const repoRoot = promptRootOverride ? resolve(promptRootOverride) : detectRepoRoot(process.cwd());
+  return join(repoRoot, "prompts", relativePath);
+}
+
+function resolveRepoDocPath(relativePath: string): string {
+  const repoRoot = detectRepoRoot(process.cwd());
+  return join(repoRoot, relativePath);
+}
+
+export function loadPromptTemplate(
+  relativePath: string,
+  replacements?: Record<string, string>,
+): string {
+  const promptPath = resolvePromptPath(relativePath);
+  let template = promptTemplateCache.get(promptPath);
+
+  if (template === undefined) {
+    template = readFileSync(promptPath, "utf8");
+    promptTemplateCache.set(promptPath, template);
+  }
+
+  if (!replacements || Object.keys(replacements).length === 0) {
+    return template;
+  }
+
+  return template.replace(TEMPLATE_TOKEN, (_match: string, token: string) => {
+    const value = replacements[token];
+    if (value === undefined) {
+      throw new Error(`[prompts] Missing replacement for "{{${token}}}" in ${promptPath}`);
+    }
+    return value;
+  });
+}
+
+export function loadRepoDocText(relativePath: string, opts?: { cache?: boolean }): string {
+  const pathValue = String(relativePath ?? "").trim();
+  if (!pathValue) {
+    throw new Error("[docs] relativePath is required");
+  }
+
+  const docPath = resolveRepoDocPath(pathValue);
+  const shouldCache = opts?.cache !== false;
+
+  if (shouldCache) {
+    const cached = repoDocCache.get(docPath);
+    if (cached !== undefined) return cached;
+  }
+
+  const text = readFileSync(docPath, "utf8");
+  if (shouldCache) {
+    repoDocCache.set(docPath, text);
+  }
+  return text;
+}

package/runtime/sandbox/packages/shared/src/repo.ts

@@ -0,0 +1,134 @@
+/**
+ * Repository utilities for detecting git root and reading context
+ */
+
+import { existsSync, readFileSync, statSync } from "fs";
+import { resolve } from "path";
+
+function resolveDotGitEntry(repoRoot: string): string {
+  return resolve(repoRoot, ".git");
+}
+
+export function findGitRepoRoot(startDir: string): string | null {
+  const override = String(process.env.PUSHPALS_REPO_ROOT_OVERRIDE ?? "").trim();
+  if (override) {
+    const resolvedOverride = resolve(override);
+    if (resolveGitMetadataDir(resolvedOverride)) {
+      return resolvedOverride;
+    }
+    console.warn(
+      `[repo] PUSHPALS_REPO_ROOT_OVERRIDE does not point to a git repository: ${resolvedOverride}`,
+    );
+  }
+
+  let current = resolve(startDir);
+  const root = resolve(current, "/");
+
+  while (current !== root) {
+    if (resolveGitMetadataDir(current)) {
+      return current;
+    }
+    current = resolve(current, "..");
+  }
+
+  return resolveGitMetadataDir(root) ? root : null;
+}
+
+export function resolveGitMetadataDir(repoRoot: string): string | null {
+  const dotGitPath = resolveDotGitEntry(repoRoot);
+  if (!existsSync(dotGitPath)) return null;
+
+  try {
+    const stat = statSync(dotGitPath);
+    if (stat.isDirectory()) {
+      return dotGitPath;
+    }
+    if (!stat.isFile()) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+
+  try {
+    const firstLine = readFileSync(dotGitPath, "utf8").split(/\r?\n/, 1)[0] ?? "";
+    const match = firstLine.match(/^gitdir:\s*(.+)\s*$/i);
+    if (!match) return null;
+    const gitDir = resolve(repoRoot, match[1].trim());
+    return existsSync(gitDir) ? gitDir : null;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveGitStateFilePath(repoRoot: string, fileName: string): string | null {
+  const gitMetadataDir = resolveGitMetadataDir(repoRoot);
+  const normalizedFileName = String(fileName ?? "").trim();
+  if (!gitMetadataDir || !normalizedFileName) return null;
+  return resolve(gitMetadataDir, normalizedFileName);
+}
+
+/**
+ * Detect git repository root by walking up from start directory.
+ * Returns the directory containing git metadata, or start directory if not found.
+ *
+ * @param startDir - Directory to start searching from (typically process.cwd())
+ * @returns Absolute path to repository root
+ */
+export function detectRepoRoot(startDir: string): string {
+  const repoRoot = findGitRepoRoot(startDir);
+  if (repoRoot) {
+    return repoRoot;
+  }
+
+  // Fallback to start directory if no .git found
+  console.warn(`[repo] No .git directory found, using: ${startDir}`);
+  return startDir;
+}
+
+/**
+ * Read basic repository context for LLM enhancement.
+ * Executes git commands to gather current branch, status, and recent commits.
+ *
+ * @param repoRoot - Absolute path to repository root
+ * @returns Repository context object
+ */
+export async function getRepoContext(repoRoot: string): Promise<{
+  branch: string;
+  status: string;
+  recentCommits: string;
+}> {
+  const git = async (args: string[]): Promise<string> => {
+    const proc = Bun.spawn(["git", ...args], {
+      cwd: repoRoot,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stdout = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      throw new Error(`git ${args[0]} failed (exit ${exitCode}): ${stderr}`);
+    }
+
+    return stdout.trim();
+  };
+
+  try {
+    const [branch, status, recentCommits] = await Promise.all([
+      git(["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "unknown"),
+      git(["status", "--porcelain"]).catch(() => "unknown"),
+      git(["log", "--oneline", "-n", "5"]).catch(() => "unknown"),
+    ]);
+
+    return { branch, status, recentCommits };
+  } catch (err) {
+    console.error("[repo] Failed to get repo context:", err);
+    return {
+      branch: "unknown",
+      status: "unknown",
+      recentCommits: "unknown",
+    };
+  }
+}

package/runtime/sandbox/packages/shared/src/session_event_visibility.ts

@@ -0,0 +1,25 @@
+type SessionEventLike = {
+  type?: string | null;
+  payload?: Record<string, unknown> | null;
+};
+
+const HEARTBEAT_STATUS_RE = /\bheartbeat\b/i;
+
+export function isHeartbeatStatusSessionEvent(event: SessionEventLike | null | undefined): boolean {
+  const type = String(event?.type ?? "")
+    .trim()
+    .toLowerCase();
+  if (type !== "status") return false;
+
+  const payload = event?.payload ?? {};
+  const detail = typeof payload.detail === "string" ? payload.detail.trim() : "";
+  const message = typeof payload.message === "string" ? payload.message.trim() : "";
+
+  return HEARTBEAT_STATUS_RE.test(detail) || HEARTBEAT_STATUS_RE.test(message);
+}
+
+export function shouldDisplayInteractiveSessionEvent(
+  event: SessionEventLike | null | undefined,
+): boolean {
+  return !isHeartbeatStatusSessionEvent(event);
+}