dr-claw 1.1.2 → 1.1.4

package/server/utils/geminiOAuth.js

@@ -0,0 +1,333 @@
+/**
+ * Gemini OAuth Token Management
+ * ==============================
+ *
+ * Reads OAuth credentials from the Gemini CLI's token store (~/.gemini/oauth_creds.json),
+ * extracts client credentials from the Gemini CLI bundle for token refresh,
+ * and provides unified auth header resolution (OAuth → API key fallback).
+ *
+ * Modeled after OpenClaw's extensions/google/oauth.* modules.
+ */
+
+import { promises as fs } from 'fs';
+import { existsSync, readFileSync, realpathSync, readdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { getGeminiApiKeyForUser } from './geminiApiKey.js';
+
+const OAUTH_CREDS_PATH = path.join(os.homedir(), '.gemini', 'oauth_creds.json');
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000; // Refresh 5 minutes early
+
+// Environment variable keys (same as OpenClaw)
+const CLIENT_ID_KEYS = [
+  'OPENCLAW_GEMINI_OAUTH_CLIENT_ID',
+  'GEMINI_CLI_OAUTH_CLIENT_ID',
+  'VIBELAB_GEMINI_OAUTH_CLIENT_ID',
+];
+const CLIENT_SECRET_KEYS = [
+  'OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET',
+  'GEMINI_CLI_OAUTH_CLIENT_SECRET',
+  'VIBELAB_GEMINI_OAUTH_CLIENT_SECRET',
+];
+
+let cachedClientCredentials = null;
+let cachedOAuthTokens = null;
+let cachedOAuthTokensMtime = 0;
+
+// ---------------------------------------------------------------------------
+// OAuth token loading & refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Load raw OAuth credentials from ~/.gemini/oauth_creds.json
+ * Returns null if the file doesn't exist.
+ */
+export async function loadGeminiOAuthTokens() {
+  try {
+    const stat = await fs.stat(OAUTH_CREDS_PATH);
+    const mtime = stat.mtimeMs;
+
+    // Use cache if file hasn't changed
+    if (cachedOAuthTokens && mtime === cachedOAuthTokensMtime) {
+      return cachedOAuthTokens;
+    }
+
+    const raw = await fs.readFile(OAUTH_CREDS_PATH, 'utf-8');
+    const tokens = JSON.parse(raw);
+    cachedOAuthTokens = tokens;
+    cachedOAuthTokensMtime = mtime;
+    return tokens;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the OAuth access token is expired (with buffer).
+ */
+export function isTokenExpired(tokens) {
+  if (!tokens?.expiry_date) return true;
+  return Date.now() >= (tokens.expiry_date - TOKEN_EXPIRY_BUFFER_MS);
+}
+
+/**
+ * Refresh the access token using the refresh_token.
+ * Writes updated credentials back to ~/.gemini/oauth_creds.json.
+ */
+export async function refreshAccessToken(tokens) {
+  if (!tokens?.refresh_token) {
+    throw new Error('No refresh token available');
+  }
+
+  const clientConfig = resolveOAuthClientConfig();
+  if (!clientConfig) {
+    throw new Error('Cannot refresh token: Gemini CLI OAuth client credentials not found. Install Gemini CLI or set GEMINI_CLI_OAUTH_CLIENT_ID/SECRET.');
+  }
+
+  const body = new URLSearchParams({
+    client_id: clientConfig.clientId,
+    client_secret: clientConfig.clientSecret,
+    refresh_token: tokens.refresh_token,
+    grant_type: 'refresh_token',
+  });
+
+  const response = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Token refresh failed (${response.status}): ${errorText}`);
+  }
+
+  const data = await response.json();
+
+  const updatedTokens = {
+    ...tokens,
+    access_token: data.access_token,
+    expiry_date: Date.now() + (data.expires_in * 1000),
+    ...(data.id_token ? { id_token: data.id_token } : {}),
+    ...(data.scope ? { scope: data.scope } : {}),
+  };
+
+  // Write back to file so Gemini CLI also benefits
+  try {
+    await fs.writeFile(OAUTH_CREDS_PATH, JSON.stringify(updatedTokens, null, 2), 'utf-8');
+    cachedOAuthTokens = updatedTokens;
+    cachedOAuthTokensMtime = Date.now();
+    console.log('[GeminiOAuth] Access token refreshed and saved.');
+  } catch (err) {
+    console.warn('[GeminiOAuth] Failed to persist refreshed token:', err.message);
+    // Still usable in-memory
+    cachedOAuthTokens = updatedTokens;
+  }
+
+  return updatedTokens;
+}
+
+/**
+ * Get a valid access token, refreshing if necessary.
+ * Returns null if no OAuth credentials are available.
+ */
+export async function getValidAccessToken() {
+  let tokens = await loadGeminiOAuthTokens();
+  if (!tokens) return null;
+
+  if (!tokens.access_token || isTokenExpired(tokens)) {
+    if (!tokens.refresh_token) return null;
+    try {
+      tokens = await refreshAccessToken(tokens);
+    } catch (err) {
+      console.error('[GeminiOAuth] Token refresh failed:', err.message);
+      return null;
+    }
+  }
+
+  return tokens.access_token;
+}
+
+// ---------------------------------------------------------------------------
+// Auth header resolution (OAuth → API key fallback)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns { headers, authMethod } for authenticating Gemini API calls.
+ * Prefers API key (consistent with queryGeminiApi env-var check), falls back to OAuth.
+ */
+export async function getGeminiAuthHeaders(userId) {
+  // Try API key first (matches queryGeminiApi precedence)
+  const apiKey = getGeminiApiKeyForUser(userId);
+  if (apiKey) {
+    return {
+      headers: { 'x-goog-api-key': apiKey },
+      authMethod: 'api-key',
+    };
+  }
+
+  // Fallback to OAuth
+  const accessToken = await getValidAccessToken();
+  if (accessToken) {
+    return {
+      headers: { 'Authorization': `Bearer ${accessToken}` },
+      authMethod: 'oauth',
+    };
+  }
+
+  return { headers: null, authMethod: null };
+}
+
+// ---------------------------------------------------------------------------
+// Client credential extraction (from Gemini CLI bundle)
+// ---------------------------------------------------------------------------
+
+function resolveEnvVar(keys) {
+  for (const key of keys) {
+    const value = process.env[key]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Extract OAuth client_id and client_secret from the Gemini CLI installation.
+ * Same approach as OpenClaw: find the gemini binary, resolve it, search for oauth2.js.
+ */
+export function extractGeminiCliCredentials() {
+  if (cachedClientCredentials) return cachedClientCredentials;
+
+  try {
+    const geminiPath = findInPath('gemini');
+    if (!geminiPath) return null;
+
+    const resolvedPath = realpathSync(geminiPath);
+    const geminiCliDirs = resolveGeminiCliDirs(geminiPath, resolvedPath);
+
+    for (const dir of geminiCliDirs) {
+      const creds = readFromKnownPaths(dir) || readFromBundle(dir) || findInTree(dir, 10);
+      if (creds) {
+        cachedClientCredentials = creds;
+        return creds;
+      }
+    }
+  } catch {
+    // Gemini CLI not installed
+  }
+  return null;
+}
+
+/**
+ * Resolve client config: env vars → Gemini CLI extraction.
+ * Returns null if neither source provides credentials.
+ */
+export function resolveOAuthClientConfig() {
+  const envClientId = resolveEnvVar(CLIENT_ID_KEYS);
+  const envClientSecret = resolveEnvVar(CLIENT_SECRET_KEYS);
+  if (envClientId && envClientSecret) {
+    return { clientId: envClientId, clientSecret: envClientSecret };
+  }
+
+  return extractGeminiCliCredentials();
+}
+
+// ---------------------------------------------------------------------------
+// Helpers for finding credentials in Gemini CLI installation
+// ---------------------------------------------------------------------------
+
+function findInPath(name) {
+  const exts = process.platform === 'win32' ? ['.cmd', '.bat', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+    for (const ext of exts) {
+      const p = path.join(dir, name + ext);
+      if (existsSync(p)) return p;
+    }
+  }
+  return null;
+}
+
+function resolveGeminiCliDirs(geminiPath, resolvedPath) {
+  const binDir = path.dirname(geminiPath);
+  const candidates = [
+    path.dirname(path.dirname(resolvedPath)),
+    path.join(path.dirname(resolvedPath), 'node_modules', '@google', 'gemini-cli'),
+    path.join(binDir, 'node_modules', '@google', 'gemini-cli'),
+    path.join(path.dirname(binDir), 'node_modules', '@google', 'gemini-cli'),
+    path.join(path.dirname(binDir), 'lib', 'node_modules', '@google', 'gemini-cli'),
+  ];
+
+  const seen = new Set();
+  return candidates.filter((dir) => {
+    const key = process.platform === 'win32' ? dir.replace(/\\/g, '/').toLowerCase() : dir;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return existsSync(path.join(dir, 'package.json')) ||
+           existsSync(path.join(dir, 'node_modules', '@google', 'gemini-cli-core'));
+  });
+}
+
+function parseCredentials(content) {
+  const clientId =
+    content.match(/OAUTH_CLIENT_ID\s*=\s*["']([^"']+)["']/)?.[1] ??
+    content.match(/(\d+-[a-z0-9]+\.apps\.googleusercontent\.com)/)?.[1];
+  const clientSecret =
+    content.match(/OAUTH_CLIENT_SECRET\s*=\s*["']([^"']+)["']/)?.[1] ??
+    content.match(/(GOCSPX-[A-Za-z0-9_-]+)/)?.[1];
+  if (!clientId || !clientSecret) return null;
+  return { clientId, clientSecret };
+}
+
+function readCredFile(filePath) {
+  try {
+    return parseCredentials(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readFromKnownPaths(geminiCliDir) {
+  const searchPaths = [
+    path.join(geminiCliDir, 'node_modules', '@google', 'gemini-cli-core', 'dist', 'src', 'code_assist', 'oauth2.js'),
+    path.join(geminiCliDir, 'node_modules', '@google', 'gemini-cli-core', 'dist', 'code_assist', 'oauth2.js'),
+  ];
+  for (const p of searchPaths) {
+    if (existsSync(p)) {
+      const creds = readCredFile(p);
+      if (creds) return creds;
+    }
+  }
+  return null;
+}
+
+function readFromBundle(geminiCliDir) {
+  const bundleDir = path.join(geminiCliDir, 'bundle');
+  if (!existsSync(bundleDir)) return null;
+  try {
+    for (const entry of readdirSync(bundleDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.js')) {
+        const creds = readCredFile(path.join(bundleDir, entry.name));
+        if (creds) return creds;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function findInTree(dir, depth) {
+  if (depth <= 0) return null;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isFile() && entry.name === 'oauth2.js') {
+        const creds = readCredFile(p);
+        if (creds) return creds;
+      }
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        const found = findInTree(p, depth - 1);
+        if (found) return found;
+      }
+    }
+  } catch {}
+  return null;
+}

package/server/utils/memoryPrompt.js

@@ -0,0 +1,78 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { memoryDb } from '../database/db.js';
+
+/**
+ * Sanitizes memory content before injecting into system prompts.
+ * Strips markdown headings that could confuse prompt structure.
+ */
+function sanitizeContent(content) {
+  return content.replace(/^#+\s/gm, '').trim();
+}
+
+/**
+ * Builds a memory block string to inject into system prompts (Option A: web UI).
+ * Returns empty string if memory is disabled for this user or no enabled memories exist.
+ * @param {number} userId - The authenticated user's ID
+ * @returns {string} Formatted memory block or empty string
+ */
+export function buildMemoryBlock(userId) {
+  if (!userId) return '';
+
+  if (!memoryDb.getMemoryEnabled(userId)) return '';
+
+  const memories = memoryDb.getEnabled(userId);
+  if (!memories || memories.length === 0) return '';
+
+  const lines = memories.map(m => `- ${sanitizeContent(m.content)}`).join('\n');
+  return `\n\n# User Memories\nThe following are things the user has asked you to remember. Incorporate them naturally into your responses where relevant:\n${lines}\n`;
+}
+
+/**
+ * Syncs enabled memories to a user-scoped reference file ~/.claude/MEMORY-{userId}.md.
+ * This file is for user reference only — Option A (web UI) injects memories via
+ * buildMemoryBlock() directly into system prompts and does not read this file.
+ * File is namespaced by userId to avoid multi-user conflicts on shared servers.
+ * @param {number} userId - The authenticated user's ID
+ */
+export async function syncMemoryFiles(userId) {
+  if (!userId) return;
+
+  const claudeDir = path.join(os.homedir(), '.claude');
+
+  try {
+    await fs.mkdir(claudeDir, { recursive: true });
+  } catch {
+    // directory likely exists
+  }
+
+  const isEnabled = memoryDb.getMemoryEnabled(userId);
+  const memories = isEnabled ? memoryDb.getEnabled(userId) : [];
+
+  const lines = [
+    '# User Memories',
+    '',
+    '> This file is a read-only reference synced by Dr. Claw.',
+    '> To manage memories: use Dr. Claw Settings > Memory tab.',
+    '',
+  ];
+
+  if (!memories || memories.length === 0) {
+    lines.push('_No memories saved yet. Add them in Dr. Claw Settings > Memory._');
+  } else {
+    for (const m of memories) {
+      const tag = m.category && m.category !== 'general' ? ` [${m.category}]` : '';
+      lines.push(`- ${sanitizeContent(m.content)}${tag}`);
+    }
+  }
+
+  lines.push('');
+
+  const memoryMdPath = path.join(claudeDir, `MEMORY-${userId}.md`);
+  try {
+    await fs.writeFile(memoryMdPath, lines.join('\n'), 'utf-8');
+  } catch (err) {
+    console.warn('[memory-sync] Failed to write MEMORY file:', err.message);
+  }
+}

package/server/utils/safePath.js

@@ -0,0 +1,51 @@
+/**
+ * Safe path resolution that prevents directory traversal.
+ *
+ * Tool calls from LLM agents may contain crafted paths like "/etc/passwd"
+ * or "../../../etc/shadow". This module ensures every resolved path stays
+ * within the designated project root, blocking prompt-injection attacks
+ * that attempt to read or write files outside the workspace.
+ *
+ * Only the *logical* resolved path is checked (no `realpathSync`).  This
+ * means legitimate symlinks inside the project that point outside the root
+ * (e.g. `data -> /mnt/storage/data`) still work, while `..` traversal and
+ * absolute-path escapes are caught.
+ */
+
+import path from 'path';
+
+/**
+ * Resolve `userPath` relative to `allowedRoot` and verify the result
+ * stays within `allowedRoot`.
+ *
+ * - Absolute paths that land outside the root are rejected.
+ * - Absolute paths inside the root are allowed (LLM may reference them).
+ * - `..` components that climb above the root are rejected.
+ * - Symlinks are NOT resolved — only the logical path is checked.
+ *
+ * @param {string} userPath  Path supplied by the tool call.
+ * @param {string} allowedRoot  Project root directory.
+ * @returns {string}  The resolved, validated absolute path.
+ * @throws {Error}  If the path escapes `allowedRoot`.
+ */
+export function safePath(userPath, allowedRoot) {
+  const normalizedRoot = path.resolve(allowedRoot);
+
+  if (!userPath) return normalizedRoot;
+
+  // Resolve to absolute (works for both relative and absolute inputs).
+  // path.resolve normalises away any `.` and `..` segments.
+  const resolved = path.isAbsolute(userPath)
+    ? path.resolve(userPath)
+    : path.resolve(normalizedRoot, userPath);
+
+  // Ensure resolved path starts with root
+  if (resolved !== normalizedRoot && !resolved.startsWith(normalizedRoot + path.sep)) {
+    throw new Error(
+      `Path traversal blocked: "${userPath}" resolves to "${resolved}" ` +
+      `which is outside the project root "${normalizedRoot}".`
+    );
+  }
+
+  return resolved;
+}

package/server/utils/sessionIndex.js

@@ -13,6 +13,8 @@ function defaultSessionName(provider) {
       return 'OpenRouter Session';
     case 'local':
       return 'Local GPU Session';
+    case 'nano':
+      return 'Nano Claude Code Session';
     default:
       return 'New Session';
   }

package/server/utils/skillExpander.js

@@ -0,0 +1,142 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Strip leading [Context: ...] prefixes the frontend injects for new sessions.
+ * Returns { prefix, body } so the prefix can be re-prepended after expansion.
+ */
+function splitContextPrefix(text) {
+  const m = text.match(/^(\s*\[Context:[^\]]*\]\s*)+/i);
+  if (!m) return { prefix: '', body: text };
+  return { prefix: m[0], body: text.slice(m[0].length) };
+}
+
+/**
+ * Build the ordered list of directories to search for a skill SKILL.md.
+ */
+function buildSkillSearchPaths(skillName, workingDir) {
+  return [
+    path.join(workingDir, '.agents', 'skills', skillName),
+    path.join(workingDir, '.claude', 'skills', skillName),
+    path.join(workingDir, '.gemini', 'skills', skillName),
+    path.join(process.cwd(), 'skills', skillName),
+    path.join(os.homedir(), '.claude', 'skills', skillName),
+  ];
+}
+
+/**
+ * Try to find the SKILL.md path for a given skill name.
+ * Returns the absolute path or null if not found.
+ */
+async function findSkillMdPath(skillName, workingDir) {
+  const searchPaths = buildSkillSearchPaths(skillName, workingDir);
+  for (const skillDir of searchPaths) {
+    try {
+      const skillMdPath = path.join(skillDir, 'SKILL.md');
+      const stat = await fs.stat(skillMdPath);
+      if (stat.isFile()) return skillMdPath;
+    } catch {
+      // not found, try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Read SKILL.md content for a given skill name.
+ */
+async function readSkillMd(skillName, workingDir) {
+  const skillMdPath = await findSkillMdPath(skillName, workingDir);
+  if (!skillMdPath) return null;
+  try {
+    const content = await fs.readFile(skillMdPath, 'utf-8');
+    if (!content.trim()) return null;
+    return { content, path: skillMdPath };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scan text for /skill-name references and return unique skill names found.
+ * Matches patterns like /aris-idea-discovery, /autoresearch:fix, etc.
+ * Skips matches that are clearly URLs (preceded by http:// or similar).
+ */
+function findNestedSkillRefs(text) {
+  const refs = new Set();
+  const pattern = /(?<![a-zA-Z0-9:.])\/([a-zA-Z][a-zA-Z0-9_-]+(?::[a-zA-Z0-9_-]+)?)\b/g;
+  let m;
+  while ((m = pattern.exec(text)) !== null) {
+    refs.add(m[1]);
+  }
+  return [...refs];
+}
+
+/**
+ * Build a sub-skill lookup table: for each /skill-name referenced in the
+ * top-level SKILL.md, resolve its file path so the model can read it on demand.
+ * Only scans one level deep — the model reads sub-skills progressively.
+ */
+async function buildSubSkillIndex(content, workingDir, topSkillName) {
+  const refs = findNestedSkillRefs(content);
+  const candidates = refs
+    .map((ref) => ({ ref, skillName: ref.includes(':') ? ref.split(':')[0] : ref }))
+    .filter(({ skillName }) => skillName !== topSkillName);
+
+  const results = await Promise.all(
+    candidates.map(async ({ ref, skillName }) => {
+      const skillMdPath = await findSkillMdPath(skillName, workingDir);
+      return skillMdPath ? { ref, path: skillMdPath } : null;
+    })
+  );
+
+  return results.filter(Boolean);
+}
+
+/**
+ * Resolve a `/skill-name` or `/skill-name:variant` slash command into the
+ * full SKILL.md content so non-Claude providers receive explicit instructions
+ * instead of an opaque slash command they cannot interpret.
+ *
+ * Sub-skill references within the expanded content are NOT inlined. Instead,
+ * a lookup table is appended so the model can read each sub-skill file on
+ * demand (progressive expansion), keeping the initial prompt small.
+ *
+ * Returns the expanded prompt string, or the original command unchanged if
+ * no matching skill is found.
+ */
+export async function expandSkillCommand(command, workingDir) {
+  if (!command || typeof command !== 'string') return command;
+
+  const { prefix, body } = splitContextPrefix(command);
+
+  const match = body.match(/^\/([a-zA-Z0-9_-]+(?::[a-zA-Z0-9_-]+)?)\s*([\s\S]*)$/);
+  if (!match) return command;
+
+  const skillCommand = match[1];
+  const remainder = (match[2] || '').trim();
+
+  const skillName = skillCommand.includes(':') ? skillCommand.split(':')[0] : skillCommand;
+  const variant = skillCommand.includes(':') ? skillCommand.split(':').slice(1).join(':') : null;
+
+  const result = await readSkillMd(skillName, workingDir);
+  if (!result) return command;
+
+  console.log(`[SkillExpander] Expanded /${skillCommand} from ${result.path}`);
+  const variantNote = variant ? `\n\n**Variant requested:** \`${variant}\`\n` : '';
+  const userContext = remainder ? `\n\n**User context:**\n${remainder}` : '';
+
+  // Build a path index for sub-skills referenced in this SKILL.md
+  const subSkillIndex = await buildSubSkillIndex(result.content, workingDir, skillName);
+
+  let subSkillNote = '';
+  if (subSkillIndex.length > 0) {
+    const lines = subSkillIndex.map(({ ref, path: p }) => `- \`/${ref}\` → \`${p}\``).join('\n');
+    subSkillNote = `\n\n## Sub-Skill Loading\n\nThis procedure references other skills via \`/skill-name\`. You are NOT running inside Claude Code CLI, so slash commands are not available. Instead, when you reach a step that calls a sub-skill, **read its SKILL.md file** and follow those instructions inline.\n\nSub-skill file locations:\n${lines}\n\nExample: when the procedure says "run \`/aris-idea-discovery\`", do:\n1. Read the corresponding SKILL.md path listed above\n2. Follow the instructions in that file\n3. Continue with the next step in the parent procedure`;
+  }
+
+  return `${prefix}# Skill: ${skillCommand}\n\nFollow the procedure below exactly.\n${variantNote}\n${result.content}${userContext}${subSkillNote}`;
+}
+
+export { findSkillMdPath };

package/server/utils/spawnAsync.js

@@ -0,0 +1,78 @@
+/**
+ * Safe child_process.spawn wrapper — shell: false, bounded output.
+ *
+ * When stdout exceeds maxBuffer the child is killed via SIGTERM.  If the
+ * child is terminated by our SIGTERM (signal === 'SIGTERM'), the promise
+ * **resolves** with the truncated data and `truncated: true`.  If the child
+ * exits non-zero for any other reason, the promise rejects normally.
+ */
+
+import { spawn } from 'child_process';
+
+/**
+ * @param {string}   command
+ * @param {string[]} args
+ * @param {object}   [options]
+ * @param {number}   [options.maxBuffer=1048576]  Max JS string length to keep (default ~1M chars)
+ * @returns {Promise<{stdout: string, stderr: string, truncated: boolean}>}
+ */
+export default function spawnAsync(command, args, options = {}) {
+  const maxBuffer = options.maxBuffer || 1024 * 1024; // 1 MB default
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      ...options,
+      shell: false,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let truncated = false;
+
+    child.stdout.on('data', (data) => {
+      if (!truncated) {
+        stdout += data.toString();
+        if (stdout.length > maxBuffer) {
+          stdout = stdout.slice(0, maxBuffer);
+          // Trim the last partial line so callers never see a phantom entry
+          const lastNewline = stdout.lastIndexOf('\n');
+          if (lastNewline > 0) stdout = stdout.slice(0, lastNewline);
+          truncated = true;
+          child.kill('SIGTERM');
+        }
+      }
+    });
+
+    child.stderr.on('data', (data) => {
+      if (stderr.length < maxBuffer) {
+        stderr += data.toString();
+        if (stderr.length > maxBuffer) {
+          stderr = stderr.slice(0, maxBuffer);
+        }
+      }
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+
+    child.on('close', (code, signal) => {
+      if (code === 0) {
+        resolve({ stdout, stderr, truncated });
+        return;
+      }
+
+      // We killed the child ourselves because stdout exceeded maxBuffer.
+      // Resolve with the truncated data so callers get partial results.
+      if (truncated && signal === 'SIGTERM') {
+        resolve({ stdout, stderr, truncated });
+        return;
+      }
+
+      const error = new Error(`Command failed: ${command} ${args.join(' ')}`);
+      error.code = code;
+      error.stdout = stdout;
+      error.stderr = stderr;
+      reject(error);
+    });
+  });
+}