agserver 1.0.0

package/server/chat.mjs

@@ -0,0 +1,256 @@
+import { execFileSync, spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { getCurrentBranch, resolveBranchNameById } from './git.mjs';
+import { findProjectById, scanProjectsRoot, getProjectSettings } from './projects.mjs';
+
+const KIRO_CLI = process.env.AGSERVER_KIRO_CLI || 'kiro-cli';
+
+// Set of worktree dirs currently alive in this process
+const activeWorktrees = new Set();
+
+// Per-worktree kiro-cli session state: worktreeDir -> { queue, pendingCount }
+const kiroSessions = new Map();
+
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;?]*[mGKHFlABCDJsu]/g, '').replace(/\x1b\][^\x07]*\x07/g, '');
+}
+
+function parseKiroOutput(stdout, stderr) {
+  const clean = stripAnsi(stdout);
+  const lines = clean.split('\n');
+  let credits, elapsed;
+  const metaMatch = stripAnsi(stderr).match(/Credits:\s*([\d.]+).*Time:\s*(\S+)/);
+  if (metaMatch) { credits = parseFloat(metaMatch[1]); elapsed = metaMatch[2]; }
+  const responseLines = [];
+  for (const line of lines) responseLines.push(line.replace(/^>\s?/, ''));
+  while (responseLines.length && !responseLines[0].trim()) responseLines.shift();
+  while (responseLines.length && !responseLines[responseLines.length - 1].trim()) responseLines.pop();
+  return { response: responseLines.join('\n'), credits, elapsed };
+}
+
+function isOwnedWorktreeDir(dirPath, baseName) {
+  const name = path.basename(dirPath);
+  if (name.startsWith(`${baseName}_wt_`)) return true;
+  if (name.startsWith(`${baseName}__wt-`)) return true;
+  if (name.startsWith('chatagent-test-') && (dirPath.startsWith('/tmp') || dirPath.startsWith('/private/tmp'))) return true;
+  return false;
+}
+
+function branchToDir(branchName) {
+  return branchName.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+function worktreeDirForBranch(repoPath, branchName) {
+  return path.join(path.dirname(repoPath), `${path.basename(repoPath)}_wt_${branchToDir(branchName)}`);
+}
+
+export function syncWorktrees(repoPath) {
+  const baseName = path.basename(repoPath);
+  const parentDir = path.dirname(repoPath);
+  let entries = [];
+  try {
+    const raw = execFileSync('git', ['-C', repoPath, 'worktree', 'list', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    entries = raw.trim().split(/\n\n+/).map(block => {
+      const wtLine = block.split('\n').find(l => l.startsWith('worktree '));
+      return wtLine ? wtLine.slice('worktree '.length).trim() : null;
+    }).filter(Boolean);
+  } catch { /* best effort */ }
+
+  for (const wtDir of entries.slice(1)) {
+    if (!isOwnedWorktreeDir(wtDir, baseName) || activeWorktrees.has(wtDir)) continue;
+    try { execFileSync('git', ['-C', repoPath, 'worktree', 'remove', '--force', wtDir], { stdio: 'ignore' }); } catch { /* best effort */ }
+    if (fs.existsSync(wtDir)) try { fs.rmSync(wtDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  try { execFileSync('git', ['-C', repoPath, 'worktree', 'prune'], { stdio: 'ignore' }); } catch { /* best effort */ }
+  try {
+    for (const name of fs.readdirSync(parentDir)) {
+      if (!name.startsWith(`${baseName}_wt_`) && !name.startsWith(`${baseName}__wt-`)) continue;
+      const fullPath = path.join(parentDir, name);
+      if (activeWorktrees.has(fullPath)) continue;
+      try { fs.rmSync(fullPath, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+  } catch { /* best effort */ }
+}
+
+export function disposeWorktrees(repoPath) {
+  const baseName = path.basename(repoPath);
+  const results = [];
+  let entries = [];
+  try {
+    const raw = execFileSync('git', ['-C', repoPath, 'worktree', 'list', '--porcelain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    entries = raw.trim().split(/\n\n+/).map(block => {
+      const lines = block.split('\n');
+      const wtLine = lines.find(l => l.startsWith('worktree '));
+      const branchLine = lines.find(l => l.startsWith('branch '));
+      return { dir: wtLine ? wtLine.slice('worktree '.length).trim() : null, branch: branchLine ? branchLine.slice('branch '.length).trim().replace(/^refs\/heads\//, '') : null };
+    }).filter(e => e.dir);
+  } catch { /* best effort */ }
+
+  for (const { dir: wtDir, branch } of entries.slice(1)) {
+    if (!isOwnedWorktreeDir(wtDir, baseName)) continue;
+    let pushed = false, pushError;
+    if (branch) {
+      try { execFileSync('git', ['-C', wtDir, 'push', 'origin', branch], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 30000 }); pushed = true; }
+      catch (e) { pushError = e.message; }
+    }
+    try { execFileSync('git', ['-C', repoPath, 'worktree', 'remove', '--force', wtDir], { stdio: 'ignore' }); } catch { /* best effort */ }
+    if (fs.existsSync(wtDir)) try { fs.rmSync(wtDir, { recursive: true, force: true }); } catch { /* best effort */ }
+    activeWorktrees.delete(wtDir);
+    kiroSessions.delete(wtDir);
+    results.push({ dir: wtDir, branch, pushed, error: pushError });
+  }
+  try { execFileSync('git', ['-C', repoPath, 'worktree', 'prune'], { stdio: 'ignore' }); } catch { /* best effort */ }
+  return results;
+}
+
+function getOrCreateWorktree(repoPath, branchName) {
+  const worktreeDir = worktreeDirForBranch(repoPath, branchName);
+  if (activeWorktrees.has(worktreeDir)) return worktreeDir;
+  const sha = execFileSync('git', ['-C', repoPath, 'rev-parse', branchName], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  execFileSync('git', ['-C', repoPath, 'worktree', 'add', '--detach', worktreeDir, sha], { stdio: ['ignore', 'ignore', 'pipe'] });
+  activeWorktrees.add(worktreeDir);
+  return worktreeDir;
+}
+
+function teardownWorktree(repoPath, worktreeDir) {
+  activeWorktrees.delete(worktreeDir);
+  kiroSessions.delete(worktreeDir);
+  try { execFileSync('git', ['-C', repoPath, 'worktree', 'remove', '--force', worktreeDir], { stdio: 'ignore' }); } catch { /* best effort */ }
+  try { fs.rmSync(worktreeDir, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+function runKiroCliOnce(worktreeDir, message, isResume) {
+  return new Promise((resolve, reject) => {
+    const args = ['chat', '--no-interactive', '--trust-all-tools', '--wrap', 'never'];
+    if (isResume) args.push('--resume');
+    args.push(message);
+    const child = spawn(KIRO_CLI, args, { cwd: worktreeDir, env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '';
+    child.stdout.on('data', c => { stdout += c.toString(); });
+    child.stderr.on('data', c => { stderr += c.toString(); });
+    child.on('close', code => {
+      if (code !== 0 && !stdout) { reject(new Error(`kiro-cli exited with code ${code}: ${stderr.slice(0, 200)}`)); return; }
+      resolve(parseKiroOutput(stdout, stderr));
+    });
+    child.on('error', reject);
+  });
+}
+
+function enqueueKiroCli(repoPath, worktreeDir, message, direct = false) {
+  let session = kiroSessions.get(worktreeDir);
+  if (!session) { session = { queue: Promise.resolve(), pendingCount: 0 }; kiroSessions.set(worktreeDir, session); }
+  const isResume = session.pendingCount > 0;
+  session.pendingCount++;
+  const resultPromise = session.queue.then(() => runKiroCliOnce(worktreeDir, message, isResume));
+  session.queue = resultPromise.catch(() => {}).then(() => {
+    session.pendingCount--;
+    if (!direct && session.pendingCount === 0) teardownWorktree(repoPath, worktreeDir);
+  });
+  return resultPromise;
+}
+
+const MAX_ATTACHMENTS = 10;
+
+function buildKiroMessage(context, messages, attachments) {
+  const parts = [];
+  if (context.filePath) parts.push(`Active file: ${context.filePath}`);
+  if (context.fileContent) parts.push(`File content:\n\`\`\`\n${context.fileContent.slice(0, 12000)}\n\`\`\``);
+  if (context.fileDiff) parts.push(`Diff:\n\`\`\`diff\n${context.fileDiff.slice(0, 8000)}\n\`\`\``);
+  const safeAttachments = Array.isArray(attachments) ? attachments.slice(0, MAX_ATTACHMENTS) : [];
+  for (const att of safeAttachments) parts.push(`Attached file: ${att.path}\n\`\`\`\n${att.content.slice(0, 8000)}\n\`\`\``);
+  const lastUser = [...messages].reverse().find(m => m.role === 'user');
+  if (lastUser) parts.push(lastUser.content);
+  return parts.join('\n\n');
+}
+
+function resolveWorktree(context) {
+  const project = findProjectById(context.projectId);
+  if (!project) return { error: 'project_not_found' };
+  const branchName = context.branchId
+    ? resolveBranchNameById(project.repoPath, context.branchId)
+    : getCurrentBranch(project.repoPath);
+  if (!branchName) return { error: 'branch_not_found' };
+
+  const { worktreeEnabled } = getProjectSettings(context.projectId);
+  if (!worktreeEnabled) {
+    // Direct mode: run kiro-cli in the repo dir, no worktree created
+    return { project, branchName, worktreeDir: project.repoPath, direct: true };
+  }
+
+  try {
+    const worktreeDir = getOrCreateWorktree(project.repoPath, branchName);
+    return { project, branchName, worktreeDir, direct: false };
+  } catch (e) {
+    return { error: `worktree_setup_failed: ${e.message}`, repoPath: project.repoPath, branchName };
+  }
+}
+
+export function handleChatStream(req, res, jsonFn) {
+  let body = '';
+  req.on('data', c => { body += c; });
+  req.on('end', () => {
+    let parsed;
+    try { parsed = JSON.parse(body); } catch { jsonFn(res, 400, { error: 'invalid_json' }); return; }
+    const { context = {}, messages = [], attachments = [] } = parsed;
+    const resolved = resolveWorktree(context);
+    if (resolved.error) {
+      console.error(`[chat/stream] ${resolved.error} project=${context.projectId} branch=${resolved.branchName}`);
+      jsonFn(res, resolved.error === 'project_not_found' || resolved.error === 'branch_not_found' ? 404 : 500, { error: resolved.error });
+      return;
+    }
+    const message = buildKiroMessage(context, messages, attachments);
+    if (!message.trim()) { jsonFn(res, 400, { error: 'empty_message' }); return; }
+    res.writeHead(200, { 'Content-Type': 'application/x-ndjson', 'Cache-Control': 'no-store', 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Headers': 'Content-Type, x-agserver-key' });
+    enqueueKiroCli(resolved.project.repoPath, resolved.worktreeDir, message, resolved.direct)
+      .then(({ response, credits, elapsed }) => {
+        if (response) res.write(JSON.stringify({ delta: response }) + '\n');
+        res.write(JSON.stringify({ done: true, credits, elapsed }) + '\n');
+        res.end();
+      })
+      .catch(err => {
+        console.error(`[chat/stream] kiro-cli error project=${context.projectId} err=${err}`);
+        res.write(JSON.stringify({ error: String(err), done: true }) + '\n');
+        res.end();
+      });
+  });
+}
+
+export function handleChatMessage(req, res, jsonFn) {
+  let body = '';
+  req.on('data', c => { body += c; });
+  req.on('end', () => {
+    let parsed;
+    try { parsed = JSON.parse(body); } catch { jsonFn(res, 400, { error: 'invalid_json' }); return; }
+    const { context = {}, messages = [], attachments = [] } = parsed;
+    const resolved = resolveWorktree(context);
+    if (resolved.error) {
+      jsonFn(res, resolved.error === 'project_not_found' || resolved.error === 'branch_not_found' ? 404 : 500, { error: resolved.error });
+      return;
+    }
+    const message = buildKiroMessage(context, messages, attachments);
+    if (!message.trim()) { jsonFn(res, 400, { error: 'empty_message' }); return; }
+    enqueueKiroCli(resolved.project.repoPath, resolved.worktreeDir, message, resolved.direct)
+      .then(({ response, credits, elapsed }) => jsonFn(res, 200, { content: response, credits, elapsed }))
+      .catch(err => {
+        console.error(`[chat/message] kiro-cli error project=${context.projectId} err=${err}`);
+        jsonFn(res, 502, { error: String(err) });
+      });
+  });
+}
+
+export function handleWorktreesDispose(req, res, jsonFn) {
+  let body = '';
+  req.on('data', c => { body += c; });
+  req.on('end', () => {
+    let parsed = {};
+    if (body.trim()) {
+      try { parsed = JSON.parse(body); } catch { jsonFn(res, 400, { error: 'invalid_json' }); return; }
+    }
+    const { projectId } = parsed;
+    const targets = projectId ? [findProjectById(projectId)].filter(Boolean) : scanProjectsRoot();
+    const report = {};
+    for (const p of targets) report[p.id] = disposeWorktrees(p.repoPath);
+    jsonFn(res, 200, { disposed: report });
+  });
+}

package/server/cli.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { execFileSync } from 'child_process';
+import { randomBytes } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { startServer } from './index.mjs';
+
+function generateApiKey() {
+  return randomBytes(24).toString('base64url'); // 32 URL-safe chars, cryptographically random
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function die(msg) {
+  console.error(`\n  error: ${msg}\n`);
+  process.exit(1);
+}
+
+function warn(msg) {
+  console.warn(`  warn:  ${msg}`);
+}
+
+function usage() {
+  console.log(`
+  Usage: agserver [path] [options]
+
+  Arguments:
+    path                 Root folder containing git repos (default: current dir)
+
+  Options:
+    -p, --port <port>    Port to listen on (default: 8765)
+    -H, --host <host>    Host to bind (default: 127.0.0.1)
+    -k, --key  <key>     API key (default: auto-generated)
+        --public         Bind to 0.0.0.0 (shorthand)
+        --version        Print version and exit
+    -h, --help           Show this help
+
+  Examples:
+    agserver ~/projects
+    agserver ~/projects --port 9000 --public
+    agserver . -p 8765 -k my-secret-key-here
+`);
+  process.exit(0);
+}
+
+// ── parse args ────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+let projectsRoot = null;
+let port = null;
+let host = null;
+let apiKey = null;
+let publicBind = false;
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '-h' || a === '--help') usage();
+  else if (a === '--version') {
+    const { API_VERSION } = await import('./index.mjs');
+    console.log(API_VERSION);
+    process.exit(0);
+  }
+  else if (a === '--public') publicBind = true;
+  else if ((a === '-p' || a === '--port') && args[i + 1]) port = Number(args[++i]);
+  else if ((a === '-H' || a === '--host') && args[i + 1]) host = args[++i];
+  else if ((a === '-k' || a === '--key') && args[i + 1]) apiKey = args[++i];
+  else if (!a.startsWith('-')) projectsRoot = a;
+  else die(`unknown option: ${a}\nRun agserver --help for usage.`);
+}
+
+// ── resolve projects root ─────────────────────────────────────────────────────
+
+const resolvedRoot = path.resolve(projectsRoot || process.env.AGSERVER_PROJECTS_ROOT || process.cwd());
+
+if (!fs.existsSync(resolvedRoot)) die(`path does not exist: ${resolvedRoot}`);
+if (!fs.statSync(resolvedRoot).isDirectory()) die(`path is not a directory: ${resolvedRoot}`);
+
+process.env.AGSERVER_PROJECTS_ROOT = resolvedRoot;
+
+// ── preflight: kiro-cli ───────────────────────────────────────────────────────
+
+const KIRO_CLI = process.env.AGSERVER_KIRO_CLI || 'kiro-cli';
+let kiroPreflight = { ok: false, version: null, authed: false };
+
+try {
+  const ver = execFileSync(KIRO_CLI, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+  kiroPreflight.ok = true;
+  kiroPreflight.version = ver;
+} catch {
+  // not installed or not on PATH
+}
+
+if (kiroPreflight.ok) {
+  // Check if kiro-cli is authenticated (best-effort: run a no-op or check config)
+  try {
+    execFileSync(KIRO_CLI, ['auth', 'status'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+    kiroPreflight.authed = true;
+  } catch (e) {
+    const out = e.stdout || e.stderr || '';
+    // treat as authed if the command doesn't exist (older kiro-cli without auth subcommand)
+    kiroPreflight.authed = !out.toLowerCase().includes('not logged') && !out.toLowerCase().includes('unauthenticated');
+  }
+}
+
+// ── startup banner ────────────────────────────────────────────────────────────
+
+console.log('');
+console.log('  agserver');
+console.log(`  projects root : ${resolvedRoot}`);
+console.log(`  port          : ${port ?? Number(process.env.AGSERVER_PORT || 8765)}`);
+
+if (!kiroPreflight.ok) {
+  warn(`kiro-cli not found on PATH (looked for: ${KIRO_CLI})`);
+  warn('Chat endpoints (/api/chat/*) will fail until kiro-cli is installed.');
+  warn('Install: https://kiro.dev/docs/cli');
+  console.log('');
+} else if (!kiroPreflight.authed) {
+  warn(`kiro-cli found (${kiroPreflight.version}) but may not be authenticated.`);
+  warn('Run: kiro-cli auth login');
+  console.log('');
+} else {
+  console.log(`  kiro-cli      : ${kiroPreflight.version} ✓`);
+}
+
+// ── start ─────────────────────────────────────────────────────────────────────
+
+if (publicBind && !host) host = '0.0.0.0';
+if (apiKey) process.env.AGSERVER_API_KEY = apiKey;
+
+// Always generate a strong random key if none provided — never fall back to the known default
+const resolvedKey = apiKey ?? process.env.AGSERVER_API_KEY ?? generateApiKey();
+
+startServer({
+  port: port ?? undefined,
+  host: host ?? undefined,
+  apiKey: resolvedKey,
+  allowWeakKey: false,
+});

package/server/files.mjs

@@ -0,0 +1,165 @@
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { runGit, runGitRaw, runGitRawBuffer, IGNORE_DIRS, IGNORE_FILES, parseLsTreeEntry } from './git.mjs';
+
+export const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.svg']);
+const LFS_POINTER_PREFIX = 'version https://git-lfs.github.com/spec/v1';
+const MAX_FILE_BYTES = 400_000;
+
+export function isLfsPointer(content) {
+  return typeof content === 'string' && content.trimStart().startsWith(LFS_POINTER_PREFIX);
+}
+
+export function isTextFile(filePath, size) {
+  if (size > MAX_FILE_BYTES) return false;
+  const ext = path.extname(filePath).toLowerCase();
+  const textExt = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.md', '.mdc', '.txt',
+    '.css', '.scss', '.sass', '.html', '.yml', '.yaml', '.xml', '.toml',
+    '.sh', '.zsh', '.bash', '.env', '.gitignore', '.npmrc',
+  ]);
+  if (textExt.has(ext)) return true;
+  return size < 100_000;
+}
+
+export function looksLikeBinaryBuffer(buffer) {
+  if (!buffer || buffer.length === 0) return false;
+  const scanLen = Math.min(buffer.length, 4096);
+  let suspicious = 0;
+  for (let i = 0; i < scanLen; i++) {
+    const b = buffer[i];
+    if (b === 0) return true;
+    if (b < 7 || (b > 14 && b < 32) || b === 127) suspicious++;
+  }
+  return suspicious / scanLen > 0.15;
+}
+
+export function smudgeLfsPointer(repoPath, pointerText) {
+  try {
+    return execFileSync('git', ['-C', repoPath, 'lfs', 'smudge'], {
+      input: pointerText, encoding: 'buffer', stdio: ['pipe', 'pipe', 'ignore'], maxBuffer: 10 * 1024 * 1024,
+    });
+  } catch { return null; }
+}
+
+export function normalizeRepoSubPath(subPath) {
+  const normalized = path.posix.normalize(`/${subPath || ''}`).replace(/^\/+/, '');
+  if (normalized === '.' || normalized === '/') return '';
+  if (normalized.startsWith('..')) throw new Error('path_outside_repo');
+  const parts = normalized.split('/').filter(Boolean);
+  if (parts.some(p => p === '.' || p === '..')) throw new Error('path_outside_repo');
+  if (parts.some(p => IGNORE_DIRS.has(p))) throw new Error('path_blocked');
+  return parts.join('/');
+}
+
+export function resolveSafePath(repoPath, subPath) {
+  const normalized = normalizeRepoSubPath(subPath);
+  const target = path.resolve(repoPath, normalized || '.');
+  const safeRoot = path.resolve(repoPath);
+  if (!(target === safeRoot || target.startsWith(`${safeRoot}${path.sep}`))) throw new Error('path_outside_repo');
+  const relative = path.relative(safeRoot, target);
+  return { target, relative: relative ? relative.split(path.sep).join('/') : '' };
+}
+
+export function readFileContent(repoPath, filePath) {
+  const { target, relative } = resolveSafePath(repoPath, filePath);
+  const stat = fs.statSync(target);
+  if (!stat.isFile()) throw new Error('not_a_file');
+  const ext = path.extname(relative).toLowerCase();
+  if (IMAGE_EXTS.has(ext) || ext === '.pdf') {
+    const raw = fs.readFileSync(target);
+    return { path: relative, content: raw.toString('base64'), size: stat.size, binary: false, image: IMAGE_EXTS.has(ext) || undefined, pdf: ext === '.pdf' || undefined, truncated: false };
+  }
+  const raw = fs.readFileSync(target);
+  const binary = !isTextFile(target, stat.size) || looksLikeBinaryBuffer(raw);
+  if (binary) return { path: relative, content: '[Binary file preview is not available in this viewer.]', size: stat.size, binary: true, truncated: false };
+  let content = raw.toString('utf8');
+  let truncated = false;
+  if (content.length > 200_000) { content = `${content.slice(0, 200_000)}\n\n[Preview truncated for large file.]`; truncated = true; }
+  return { path: relative, content, size: stat.size, binary: false, truncated };
+}
+
+export function readFileContentFromRef(repoPath, ref, filePath) {
+  const relative = normalizeRepoSubPath(filePath);
+  if (!relative) throw new Error('missing_file_path');
+  const fileSpec = `${ref}:${relative}`;
+  if (runGit(repoPath, ['cat-file', '-e', fileSpec], 'missing') === 'missing') throw new Error('file_not_found');
+  const size = Number(runGit(repoPath, ['cat-file', '-s', fileSpec], '0')) || 0;
+  const ext = path.extname(relative).toLowerCase();
+  if (IMAGE_EXTS.has(ext) || ext === '.pdf') {
+    const raw = runGitRawBuffer(repoPath, ['show', fileSpec]);
+    const asText = raw.toString('utf8');
+    if (isLfsPointer(asText)) {
+      const smudged = smudgeLfsPointer(repoPath, asText);
+      if (smudged) return { path: relative, content: smudged.toString('base64'), size, binary: false, image: IMAGE_EXTS.has(ext) || undefined, pdf: ext === '.pdf' || undefined, truncated: false };
+      return { path: relative, content: '', size, binary: false, lfs: true, truncated: false };
+    }
+    return { path: relative, content: raw.toString('base64'), size, binary: false, image: IMAGE_EXTS.has(ext) || undefined, pdf: ext === '.pdf' || undefined, truncated: false };
+  }
+  const raw = runGitRawBuffer(repoPath, ['show', fileSpec]);
+  const binary = !isTextFile(relative, size) || looksLikeBinaryBuffer(raw);
+  if (binary) return { path: relative, content: '[Binary file preview is not available in this viewer.]', size, binary: true, truncated: false };
+  let content = raw.toString('utf8');
+  if (isLfsPointer(content)) {
+    const smudged = smudgeLfsPointer(repoPath, content);
+    if (smudged) {
+      if (looksLikeBinaryBuffer(smudged)) return { path: relative, content: smudged.toString('base64'), size, binary: false, image: IMAGE_EXTS.has(ext) || undefined, truncated: false };
+      content = smudged.toString('utf8');
+    } else {
+      return { path: relative, content: '', size, binary: false, lfs: true, truncated: false };
+    }
+  }
+  let truncated = false;
+  if (content.length > 200_000) { content = `${content.slice(0, 200_000)}\n\n[Preview truncated for large file.]`; truncated = true; }
+  return { path: relative, content, size, binary: false, truncated };
+}
+
+export function listDirChunk(repoPath, subPath, levels) {
+  const { target, relative } = resolveSafePath(repoPath, subPath);
+  if (!fs.statSync(target).isDirectory()) return [];
+  const entries = fs.readdirSync(target, { withFileTypes: true })
+    .filter(e => e.isDirectory() ? !IGNORE_DIRS.has(e.name) : !IGNORE_FILES.has(e.name))
+    .sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+  return entries.map(entry => {
+    const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+    const childAbs = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      let hasChildren = true, children;
+      if (levels > 1) { children = listDirChunk(repoPath, childRelative, levels - 1); }
+      else { try { hasChildren = fs.readdirSync(childAbs).length > 0; } catch { hasChildren = false; } }
+      return { name: entry.name, path: childRelative, type: 'dir', hasChildren, children };
+    }
+    const fileStat = fs.statSync(childAbs);
+    return { name: entry.name, path: childRelative, type: 'file', size: fileStat.size, ext: path.extname(entry.name).toLowerCase(), hasChildren: false };
+  });
+}
+
+export function listDirChunkFromRef(repoPath, ref, subPath, levels) {
+  const relative = normalizeRepoSubPath(subPath);
+  const treeSpec = relative ? `${ref}:${relative}` : `${ref}:`;
+  const lsRaw = runGitRaw(repoPath, ['ls-tree', '-z', '--long', treeSpec], '');
+  if (!lsRaw) return [];
+  return lsRaw.split('\0').filter(Boolean)
+    .map(parseLsTreeEntry).filter(Boolean)
+    .filter(e => e.objectType === 'tree' ? !IGNORE_DIRS.has(e.name) : !IGNORE_FILES.has(e.name))
+    .sort((a, b) => {
+      if (a.objectType === 'tree' && b.objectType !== 'tree') return -1;
+      if (a.objectType !== 'tree' && b.objectType === 'tree') return 1;
+      return a.name.localeCompare(b.name);
+    })
+    .map(entry => {
+      const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.objectType === 'tree') {
+        let hasChildren = true, children;
+        if (levels > 1) { children = listDirChunkFromRef(repoPath, ref, childRelative, levels - 1); }
+        else { hasChildren = Boolean(runGitRaw(repoPath, ['ls-tree', '-z', '--long', `${ref}:${childRelative}`], '')); }
+        return { name: entry.name, path: childRelative, type: 'dir', hasChildren, children };
+      }
+      return { name: entry.name, path: childRelative, type: 'file', size: entry.size ?? 0, ext: path.extname(entry.name).toLowerCase(), hasChildren: false };
+    });
+}