@studio-foundation/cli 0.3.0-beta.1

package/src/output/progress.ts

@@ -0,0 +1,414 @@
+import chalk from 'chalk';
+import ora, { type Ora } from 'ora';
+import type { EngineEvents } from '@studio-foundation/engine';
+import { formatDuration } from './formatter.js';
+import { summarizeToolCalls, getToolIcon, summarizeToolParams, summarizeToolResult, formatStageOutput, formatToolResult, formatTokens, formatStageLine, countWriteFiles } from './formatters.js';
+import { ParallelRenderer } from './parallel-progress.js';
+
+export class ProgressDisplay {
+  private spinner: Ora | null = null;
+  private spinnerText = '';
+  private toolSpinner: Ora | null = null;
+  private thinkingSpinner: Ora | null = null;
+  private currentToolText = '';
+  private isStreamingTokens = false;
+  private stageStartTime = 0;
+  private timerInterval: ReturnType<typeof setInterval> | null = null;
+
+  // Parallel group rendering
+  private isInParallelGroup = false;
+  private parallelRenderer: ParallelRenderer | null = null;
+
+  // State tracking for stage progress
+  runId = '';
+  private currentAttempt = 1;
+  private currentStageIndex = 0;
+  private currentTotalStages = 0;
+  private currentStageName = '';
+
+  readonly live: boolean;
+  readonly verbose: boolean;
+
+  constructor(
+    private jsonMode: boolean,
+    mode: 'quiet' | 'verbose' | 'live' | { live: boolean; verbose: boolean }
+  ) {
+    if (typeof mode === 'string') {
+      this.live = mode === 'live';
+      this.verbose = mode === 'verbose';
+    } else {
+      this.live = mode.live;
+      this.verbose = mode.verbose;
+    }
+  }
+
+  private resetStageTimer(): void {
+    this.stageStartTime = Date.now();
+  }
+
+  private startTimer(updateFn: (elapsed: string) => void): void {
+    this.timerInterval = setInterval(() => {
+      const s = Math.floor((Date.now() - this.stageStartTime) / 1000);
+      updateFn(`${s}s`);
+    }, 1000);
+  }
+
+  private clearTimer(): void {
+    if (this.timerInterval) {
+      clearInterval(this.timerInterval);
+      this.timerInterval = null;
+    }
+  }
+
+  private elapsedSeconds(): number {
+    return Math.floor((Date.now() - this.stageStartTime) / 1000);
+  }
+
+  interrupt(): void {
+    this.clearTimer();
+    this.parallelRenderer?.interrupt();
+    this.parallelRenderer = null;
+    this.isInParallelGroup = false;
+    if (this.isStreamingTokens) {
+      process.stdout.write('\n');
+      this.isStreamingTokens = false;
+    }
+    this.toolSpinner?.stop();
+    this.toolSpinner = null;
+    this.thinkingSpinner?.stop();
+    this.thinkingSpinner = null;
+    this.spinner?.stop();
+    this.spinner = null;
+  }
+
+  getEvents(): EngineEvents {
+    return {
+      onPipelineStart: (event) => {
+        if (this.jsonMode) return;
+        this.runId = event.run_id;
+        console.log(chalk.blue(`\nRunning pipeline: ${event.pipeline_name}\n`));
+      },
+
+      onStageStart: (event) => {
+        if (this.jsonMode) return;
+        this.currentStageIndex = event.stage_index;
+        this.currentTotalStages = event.total_stages;
+        this.currentStageName = event.stage_name;
+        this.currentAttempt = 1;
+        const prefix = `[${event.stage_index + 1}/${event.total_stages}]`;
+
+        if (this.isInParallelGroup) {
+          // Parallel mode: delegate to multi-line renderer (no ora spinner)
+          this.parallelRenderer!.addStage(prefix, event.stage_name);
+          return;
+        }
+
+        if (this.live) {
+          console.log(chalk.cyan(`${formatStageLine(prefix, event.stage_name, '')}...`));
+          this.thinkingSpinner = ora({ text: chalk.dim('Thinking... (0s)'), indent: 2, color: 'gray' }).start();
+          this.resetStageTimer();
+          this.startTimer((elapsed) => {
+            if (this.thinkingSpinner) {
+              this.thinkingSpinner.text = chalk.dim(`Thinking... (${elapsed})`);
+            }
+          });
+        } else {
+          this.spinnerText = formatStageLine(prefix, event.stage_name, '');
+          this.spinner = ora({ text: this.spinnerText, color: 'cyan' }).start();
+          this.resetStageTimer();
+          this.startTimer((elapsed) => {
+            if (this.spinner) {
+              this.spinner.text = formatStageLine(prefix, event.stage_name, `(${elapsed})`);
+            }
+          });
+        }
+      },
+
+      onStageComplete: (event) => {
+        if (this.jsonMode) return;
+
+        const duration = formatDuration(event.duration_ms);
+        const prefix = `[${event.stage_index + 1}/${event.total_stages}]`;
+
+        // Build compact info parts: duration, tokens, files
+        const infoParts: string[] = [duration];
+        if (event.token_usage && event.token_usage.total_tokens > 0) {
+          infoParts.push(`${formatTokens(event.token_usage.total_tokens)} tokens`);
+        }
+        const filesWritten = event.tool_calls ? countWriteFiles(event.tool_calls) : 0;
+        if (filesWritten > 0) {
+          infoParts.push(`${filesWritten} file${filesWritten !== 1 ? 's' : ''}`);
+        }
+        const infoStr = infoParts.join(', ');
+
+        if (this.isInParallelGroup) {
+          // Parallel mode: freeze the line with final status
+          let finalText: string;
+          if (event.status === 'success') {
+            finalText = formatStageLine(prefix, event.stage_name, chalk.green('✓') + chalk.gray(` (${infoStr})`));
+          } else if (event.status === 'rejected') {
+            finalText = formatStageLine(prefix, event.stage_name, chalk.red('✗ rejected') + chalk.gray(` (${duration})`));
+          } else {
+            finalText = formatStageLine(prefix, event.stage_name, chalk.red('✗ failed') + chalk.gray(` (${infoStr})`));
+          }
+          this.parallelRenderer?.completeStage(event.stage_name, finalText);
+          return;
+        }
+
+        if (this.live) {
+          if (this.isStreamingTokens) {
+            process.stdout.write('\n');
+            this.isStreamingTokens = false;
+          }
+          this.clearTimer();
+          this.thinkingSpinner?.stop();
+          this.thinkingSpinner = null;
+          if (event.status === 'success') {
+            console.log(chalk.green(`  ✓`) + chalk.gray(` (${infoStr})`));
+          } else if (event.status === 'rejected') {
+            console.log(chalk.red(`  ✗ rejected`) + chalk.gray(` (${duration})`));
+            if (event.rejection_reason) console.log(chalk.red(`    ${event.rejection_reason}`));
+            if (event.rejection_details?.length) {
+              for (const detail of event.rejection_details) {
+                console.log(chalk.yellow(`      - ${detail}`));
+              }
+            }
+          } else {
+            console.log(chalk.red(`  ✗ failed`) + chalk.gray(` (${infoStr})`));
+          }
+        } else if (event.status === 'success') {
+          this.spinner?.succeed(
+            formatStageLine(prefix, event.stage_name, chalk.green('✓') + chalk.gray(` (${infoStr})`))
+          );
+        } else if (event.status === 'rejected') {
+          this.spinner?.fail(
+            formatStageLine(prefix, event.stage_name, chalk.red('✗ rejected') + chalk.gray(` (${duration})`))
+          );
+          if (event.rejection_reason) {
+            console.log(chalk.red(`  ${event.rejection_reason}`));
+          }
+          if (event.rejection_details?.length) {
+            for (const detail of event.rejection_details) {
+              console.log(chalk.yellow(`    - ${detail}`));
+            }
+          }
+        } else {
+          this.spinner?.fail(
+            formatStageLine(prefix, event.stage_name, chalk.red('✗ failed') + chalk.gray(` (${infoStr})`))
+          );
+        }
+        this.clearTimer();
+        this.spinner = null;
+
+        // Tool call summary: quiet + verbose only (in live mode, each was shown individually)
+        if (!this.live && event.tool_calls && event.tool_calls.length > 0) {
+          const summary = summarizeToolCalls(event.tool_calls);
+          if (summary) console.log(chalk.gray(`  ${summary}`));
+        }
+
+        // Formatted output: verbose only
+        if (this.verbose && event.status !== 'rejected' && event.output && typeof event.output === 'object') {
+          const depth = Infinity;
+          const formatted = formatStageOutput(event.output as Record<string, unknown>, depth);
+          if (formatted) {
+            for (const line of formatted.split('\n')) {
+              console.log(chalk.gray(`  ${line}`));
+            }
+          }
+        }
+
+        // Token breakdown: verbose mode (both standalone and live+verbose)
+        if (this.verbose && event.token_usage) {
+          const u = event.token_usage;
+          console.log(chalk.gray(`  Tokens: ${u.prompt_tokens} prompt + ${u.completion_tokens} completion = ${u.total_tokens} total`));
+        }
+      },
+
+      onTaskRetry: (event) => {
+        if (this.jsonMode) return;
+
+        if (this.isInParallelGroup) {
+          // In parallel mode the spinner keeps running; nothing to do here.
+          return;
+        }
+
+        this.clearTimer();
+        // Stop any active spinners before printing retry info
+        if (this.isStreamingTokens) {
+          process.stdout.write('\n');
+          this.isStreamingTokens = false;
+        }
+        this.toolSpinner?.stop();
+        this.toolSpinner = null;
+        this.thinkingSpinner?.stop();
+        this.thinkingSpinner = null;
+
+        this.currentAttempt = event.attempt + 1;
+        const prefix = `[${this.currentStageIndex + 1}/${this.currentTotalStages}]`;
+        const reason = event.failures.length > 0 ? event.failures[0] : 'validation failed';
+
+        if (this.live) {
+          console.log(chalk.yellow(`  ✗ retry (${reason})`));
+        } else {
+          this.spinner?.fail(
+            formatStageLine(prefix, this.currentStageName, chalk.yellow('✗ retry') + chalk.gray(` (${reason})`))
+          );
+          this.spinner = null;
+        }
+
+        // Verbose extras
+        if (this.verbose && event.failures.length > 1) {
+          for (const failure of event.failures.slice(1)) {
+            console.log(chalk.yellow(`    - ${failure}`));
+          }
+        }
+        if (this.verbose && event.agent_output_raw) {
+          console.log(chalk.gray(`    Raw response: ${event.agent_output_raw.slice(0, 300)}`));
+        }
+
+        // Restart spinner with next attempt counter
+        if (!this.live) {
+          const suffix = `(attempt ${this.currentAttempt}/${event.max_attempts})`;
+          this.spinnerText = formatStageLine(prefix, this.currentStageName, suffix);
+          this.spinner = ora({ text: this.spinnerText, color: 'cyan' }).start();
+        }
+      },
+
+      onGroupStart: (event) => {
+        if (event.parallel) {
+          this.isInParallelGroup = true;
+          this.parallelRenderer = new ParallelRenderer();
+        }
+        // Otherwise silent — sequential group is transparent at the pipeline level
+      },
+
+      onGroupIteration: (event) => {
+        if (this.jsonMode) return;
+        if (event.iteration > 1) {
+          console.log(chalk.yellow(`\n  ↻ Feedback loop iteration ${event.iteration}/${event.max_iterations}`));
+        }
+      },
+
+      onGroupFeedback: (event) => {
+        if (this.jsonMode) return;
+        console.log(chalk.yellow(`    Rejected: ${event.rejection_reason}`));
+        if (this.verbose && event.rejection_details.length > 0) {
+          for (const detail of event.rejection_details) {
+            console.log(chalk.yellow(`      - ${detail}`));
+          }
+        }
+        console.log(chalk.yellow(`    Re-running with feedback...`));
+      },
+
+      onGroupComplete: (event) => {
+        if (this.isInParallelGroup) {
+          this.parallelRenderer?.stop();
+          this.parallelRenderer = null;
+          this.isInParallelGroup = false;
+        }
+        if (this.jsonMode) return;
+        if (event.iterations > 1) {
+          if (event.status === 'success') {
+            console.log(chalk.green(`  ✓ Approved after ${event.iterations} iterations`));
+          } else {
+            console.log(chalk.red(`  ✗ Rejected after ${event.iterations} iterations (max reached)`));
+          }
+        }
+      },
+
+      onAgentThinking: (event) => {
+        if (this.jsonMode || !this.live || this.isInParallelGroup) return;
+        for (const line of event.thought.trim().split('\n')) {
+          const trimmed = line.trim();
+          if (trimmed) console.log(chalk.dim(`  🤔 ${trimmed}`));
+        }
+      },
+
+      onAgentProgress: (event) => {
+        if (this.jsonMode || !this.live || this.isInParallelGroup) return;
+        for (const line of event.message.trim().split('\n')) {
+          const trimmed = line.trim();
+          if (trimmed) console.log(chalk.dim(`  💭 ${trimmed}`));
+        }
+      },
+
+      onAgentToken: (event) => {
+        if (this.jsonMode || !this.live || this.isInParallelGroup) return;
+        if (this.thinkingSpinner) {
+          this.clearTimer();
+          this.thinkingSpinner.stop();
+          this.thinkingSpinner = null;
+          process.stdout.write('  '); // indent to match spinner position
+        }
+        this.isStreamingTokens = true;
+        process.stdout.write(chalk.dim(event.token));
+      },
+
+      onToolCallStart: (event) => {
+        if (this.jsonMode || !this.live || this.isInParallelGroup) return;
+        // End any in-progress token stream line before starting tool spinner
+        if (this.isStreamingTokens) {
+          process.stdout.write('\n');
+          this.isStreamingTokens = false;
+        }
+        this.clearTimer();
+        this.thinkingSpinner?.stop();
+        this.thinkingSpinner = null;
+        const icon = getToolIcon(event.tool);
+        const params = summarizeToolParams(event.tool, event.params);
+        this.currentToolText = `${icon} ${event.tool}${params}`;
+        this.toolSpinner = ora({
+          text: chalk.white(this.currentToolText),
+          indent: 2,
+          color: 'cyan',
+        }).start();
+      },
+
+      onToolCallComplete: (event) => {
+        if (this.jsonMode || !this.live || this.isInParallelGroup) return;
+        const summary = summarizeToolResult(event.result, event.error);
+        if (event.error) {
+          this.toolSpinner?.fail(chalk.red(`${this.currentToolText} — ${event.error}`));
+        } else {
+          this.toolSpinner?.succeed(chalk.white(this.currentToolText) + chalk.gray(` → ${summary}`));
+        }
+        this.toolSpinner = null;
+
+        // Verbose: print full tool result below the spinner line
+        if (this.verbose && !event.error) {
+          const full = formatToolResult(event.result);
+          for (const line of full.split('\n')) {
+            console.log(chalk.gray(line));
+          }
+        }
+
+        // Restart thinking spinner even on error — LLM still processes the result and may retry
+        const fromSec = this.elapsedSeconds();
+        this.thinkingSpinner = ora({ text: chalk.dim(`Thinking... (from ${fromSec}s)`), indent: 2, color: 'gray' }).start();
+        this.thinkingSpinner.text = chalk.dim(`Thinking... (from ${fromSec}s)`);
+        this.startTimer((elapsed) => {
+          if (this.thinkingSpinner) {
+            this.thinkingSpinner.text = chalk.dim(`Thinking... (from ${elapsed})`);
+          }
+        });
+      },
+
+      onPipelineComplete: (event) => {
+        if (this.jsonMode) return;
+
+        console.log('');
+        const duration = formatDuration(event.duration_ms);
+        const tokenStr = event.total_tokens > 0 ? `, ${formatTokens(event.total_tokens)} tokens` : '';
+        const toolStr = event.total_tool_calls > 0 ? `, ${event.total_tool_calls} tool calls` : '';
+
+        if (event.status === 'success') {
+          console.log(chalk.green('✓ Pipeline completed') + chalk.gray(` (${duration}${tokenStr}${toolStr})`));
+        } else if (event.status === 'rejected') {
+          console.log(chalk.red('✗ Pipeline rejected') + chalk.gray(` (${duration}${tokenStr})`));
+        } else {
+          console.log(chalk.red('✗ Pipeline failed') + chalk.gray(` (${duration}${tokenStr})`));
+        }
+      },
+    };
+  }
+}

package/src/provider-validator.ts

@@ -0,0 +1,109 @@
+import { parseAndCacheModels } from './models-cache.js';
+
+export type ValidationResult =
+  | { status: 'valid' }
+  | { status: 'invalid'; error: string }
+  | { status: 'warning'; message: string };
+
+export interface ValidateOptions {
+  baseUrl?: string;
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export async function validateApiKeyLive(
+  provider: string,
+  apiKey: string,
+  options: ValidateOptions = {}
+): Promise<ValidationResult> {
+  const abort = new AbortController();
+  const timer = setTimeout(
+    () => abort.abort(),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+
+  try {
+    if (provider === 'anthropic') {
+      return await validateAnthropicKey(apiKey, abort.signal);
+    } else if (provider === 'openai') {
+      return await validateOpenAIKey(apiKey, abort.signal);
+    } else if (provider === 'google') {
+      return await validateGoogleKey(apiKey, abort.signal);
+    } else if (provider === 'ollama') {
+      return await validateLocalOllama(
+        options.baseUrl ?? 'http://localhost:11434',
+        abort.signal
+      );
+    } else {
+      return { status: 'warning', message: `Cannot validate unknown provider '${provider}'` };
+    }
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortError') {
+      return { status: 'warning', message: 'Validation timed out — proceeding anyway' };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { status: 'warning', message: `Could not validate key: ${message}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function validateAnthropicKey(
+  apiKey: string,
+  signal: AbortSignal
+): Promise<ValidationResult> {
+  const res = await fetch('https://api.anthropic.com/v1/models', {
+    signal,
+    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
+  });
+  if (res.status === 200) {
+    try { parseAndCacheModels('anthropic', apiKey, await res.json()); } catch { /* ignore */ }
+    return { status: 'valid' };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { status: 'invalid', error: `Invalid key (${res.status} Unauthorized)` };
+  }
+  return { status: 'warning', message: `Unexpected response ${res.status} — proceeding anyway` };
+}
+
+async function validateOpenAIKey(
+  apiKey: string,
+  signal: AbortSignal
+): Promise<ValidationResult> {
+  const res = await fetch('https://api.openai.com/v1/models', {
+    signal,
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (res.status === 200) {
+    try { parseAndCacheModels('openai', apiKey, await res.json()); } catch { /* ignore */ }
+    return { status: 'valid' };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { status: 'invalid', error: `Invalid key (${res.status} Unauthorized)` };
+  }
+  return { status: 'warning', message: `Unexpected response ${res.status} — proceeding anyway` };
+}
+
+async function validateGoogleKey(
+  apiKey: string,
+  signal: AbortSignal
+): Promise<ValidationResult> {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}`;
+  const res = await fetch(url, { signal });
+  if (res.status === 200) return { status: 'valid' };
+  if (res.status === 400 || res.status === 403) {
+    return { status: 'invalid', error: `Invalid key (${res.status})` };
+  }
+  return { status: 'warning', message: `Unexpected response ${res.status} — proceeding anyway` };
+}
+
+async function validateLocalOllama(
+  baseUrl: string,
+  signal: AbortSignal
+): Promise<ValidationResult> {
+  const url = baseUrl.replace(/\/$/, '') + '/api/tags';
+  const res = await fetch(url, { signal });
+  if (res.status === 200) return { status: 'valid' };
+  return { status: 'warning', message: `Ollama returned ${res.status} — proceeding anyway` };
+}

package/src/registry/cache.ts

@@ -0,0 +1,46 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { RegistryIndex } from './types.js';
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+interface CachedIndex extends RegistryIndex {
+  _cached_at: string;
+}
+
+export class RegistryCache {
+  private cacheDir: string;
+  private cachePath: string;
+
+  constructor(cacheDir?: string) {
+    this.cacheDir = cacheDir ?? resolve(homedir(), '.cache', 'studio', 'registry');
+    this.cachePath = resolve(this.cacheDir, 'index.json');
+  }
+
+  async read(): Promise<RegistryIndex | null> {
+    let raw: string;
+    try {
+      raw = await readFile(this.cachePath, 'utf8');
+    } catch {
+      return null;
+    }
+
+    const data = JSON.parse(raw) as CachedIndex;
+    const age = Date.now() - new Date(data._cached_at).getTime();
+    if (age > CACHE_TTL_MS) return null;
+
+    const { _cached_at: _, ...index } = data;
+    return index as RegistryIndex;
+  }
+
+  async write(index: RegistryIndex): Promise<void> {
+    await mkdir(this.cacheDir, { recursive: true });
+    const data: CachedIndex = { ...index, _cached_at: new Date().toISOString() };
+    await writeFile(this.cachePath, JSON.stringify(data, null, 2) + '\n');
+  }
+
+  async isFresh(): Promise<boolean> {
+    return (await this.read()) !== null;
+  }
+}

package/src/registry/client.ts

@@ -0,0 +1,84 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import type { RegistryIndex, PackageMetadata, PackageType } from './types.js';
+import { REGISTRY_RAW_BASE, REGISTRY_API_BASE } from './types.js';
+
+interface GitHubContentItem {
+  name: string;
+  path: string;
+  type: 'file' | 'dir';
+  download_url: string | null;
+}
+
+export class RegistryClient {
+  async fetchIndex(): Promise<RegistryIndex> {
+    const res = await fetch(`${REGISTRY_RAW_BASE}/index.json`);
+    if (!res.ok) throw new Error(`Failed to fetch registry index: HTTP ${res.status}`);
+    return res.json() as Promise<RegistryIndex>;
+  }
+
+  async fetchMetadata(type: PackageType, name: string): Promise<PackageMetadata> {
+    const res = await fetch(`${REGISTRY_RAW_BASE}/${type}s/${name}/metadata.json`);
+    if (!res.ok) throw new Error(`Package '${name}' not found in registry`);
+    return res.json() as Promise<PackageMetadata>;
+  }
+
+  /**
+   * Download a single-file package (tool, pipeline, integration, agent, skill).
+   * Returns { destPath, sha256 }.
+   */
+  async downloadFile(
+    type: PackageType,
+    name: string,
+    filename: string,
+    destDir: string,
+  ): Promise<{ destPath: string; sha256: string }> {
+    const url = `${REGISTRY_RAW_BASE}/${type}s/${name}/${filename}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to download ${filename}: HTTP ${res.status}`);
+    const content = await res.text();
+    const destPath = resolve(destDir, filename);
+    await mkdir(destDir, { recursive: true });
+    await writeFile(destPath, content);
+    const sha256 = createHash('sha256').update(content).digest('hex');
+    return { destPath, sha256 };
+  }
+
+  /**
+   * Download a directory package (template, plugin) via GitHub API.
+   * Returns SHA256 of all file contents concatenated (sorted by path).
+   */
+  async downloadDirectory(
+    type: PackageType,
+    name: string,
+    remotePath: string,
+    localDestDir: string,
+  ): Promise<string> {
+    const res = await fetch(
+      `${REGISTRY_API_BASE}/contents/${type}s/${name}/${remotePath}`,
+      { headers: { Accept: 'application/vnd.github+json' } },
+    );
+    if (!res.ok) throw new Error(`Failed to list directory: HTTP ${res.status}`);
+    const items = (await res.json()) as GitHubContentItem[];
+
+    const hash = createHash('sha256');
+    const sortedItems = [...items].sort((a, b) => a.path.localeCompare(b.path));
+
+    for (const item of sortedItems) {
+      const localPath = resolve(localDestDir, item.name);
+      if (item.type === 'dir') {
+        await this.downloadDirectory(type, name, `${remotePath}/${item.name}`, localPath);
+      } else if (item.download_url) {
+        const fileRes = await fetch(item.download_url);
+        if (!fileRes.ok) throw new Error(`Failed to download ${item.path}`);
+        const content = await fileRes.text();
+        await mkdir(dirname(localPath), { recursive: true });
+        await writeFile(localPath, content);
+        hash.update(item.path + content);
+      }
+    }
+
+    return hash.digest('hex');
+  }
+}