shilo-cli 0.6.0 → 0.8.0

package/src/ShiloClient.js

@@ -1,706 +1,1027 @@
-'use strict';
-
-/**
- * Cliente HTTP para la API de Shilo. Portado del ShiloClient de
- * Bnei-Yerushalaim-Cloud, adaptado a `fetch` nativo (Node >=18, cero deps).
- *
- * Autenticación (Fase 1):
- *   - authenticate(email, password)
- *   - refreshToken(refreshToken)         (requiere supabaseUrl + anonKey)
- *   - ensureValidToken(credentials)
- *
- * Archivos y commits (Fase 2):
- *   - listFiles / getFileMeta / readFile
- *   - createFile / writeFile / writeBatch / createFolder / ensurePath
- *   - createCommit
- *
- * Todos los métodos de red toman `credentials` y devuelven `{ ..., credentials }`
- * con las credenciales posiblemente refrescadas, para que el caller las persista.
- */
-
-const DEFAULT_BASE_URL = 'https://www.shilo.city';
-const DEFAULT_TIMEOUT_MS = 45000;
-
-// Reintentos: sólo para fallos que pueden desaparecer solos (red, timeout, 429,
-// 5xx). Un 4xx que no sea 429 es un error del cliente —ruta inválida, permisos,
-// body mal formado— y repetirlo sólo gasta tiempo.
-const DEFAULT_RETRIES = 3;
-const RETRY_BASE_MS = 250;
-const RETRY_MAX_MS = 8000;
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-/**
- * Backoff exponencial con jitter completo. El jitter importa: sin él, N
- * requests que chocan con el mismo 429 reintentan todos en el mismo
- * milisegundo y vuelven a chocar.
- */
-function backoffDelay(attempt) {
-  const ceiling = Math.min(RETRY_BASE_MS * Math.pow(4, attempt), RETRY_MAX_MS);
-  return Math.round(ceiling * (0.5 + Math.random() * 0.5));
-}
-
-/** Lee `Retry-After` (segundos o fecha HTTP). Devuelve ms, o null. */
-function retryAfterMs(res) {
-  const raw = res && res.headers && res.headers.get && res.headers.get('retry-after');
-  if (!raw) return null;
-  const secs = Number(raw);
-  if (Number.isFinite(secs)) return Math.max(0, Math.min(secs * 1000, 60000));
-  const when = Date.parse(raw);
-  if (!Number.isNaN(when)) return Math.max(0, Math.min(when - Date.now(), 60000));
-  return null;
-}
-
-/**
- * El ápex https://shilo.city responde 307 hacia https://www.shilo.city. Como
- * `fetch` sigue redirects pero descarta el header Authorization al cruzar de
- * origen, apuntar al ápex haría fallar con 401 todo lo autenticado (push, pull,
- * projects). Normalizamos a www para que nunca ocurra ese salto.
- */
-function normalizeBaseURL(url) {
-  const clean = String(url).replace(/\/+$/, '');
-  return clean.replace(/^(https?:\/\/)shilo\.city(?=$|\/)/i, '$1www.shilo.city');
-}
-
-class ShiloError extends Error {
-  constructor(message, { status = null, body = null, retryable = false, notSupported = false } = {}) {
-    super(message);
-    this.name = 'ShiloError';
-    this.status = status;
-    this.body = body;
-    this.retryable = retryable;
-    // El servidor no conoce el endpoint (deploy viejo): el caller puede usar
-    // el camino alternativo en vez de abortar.
-    this.notSupported = notSupported;
-  }
-}
-
-class ShiloClient {
-  constructor(options = {}) {
-    this.baseURL = normalizeBaseURL(options.baseURL || DEFAULT_BASE_URL);
-    this.timeoutMs = Number(options.timeoutMs) || DEFAULT_TIMEOUT_MS;
-    // Opcionales: habilitan refresh de token sin re-login.
-    this.supabaseUrl = options.supabaseUrl || null;
-    this.supabaseAnonKey = options.supabaseAnonKey || null;
-    this.retries = options.retries != null ? Number(options.retries) : DEFAULT_RETRIES;
-    // Se avisa de cada 429 para que el caller pueda bajar la concurrencia en vez
-    // de seguir martillando al servidor con la misma cadencia.
-    this.onThrottle = typeof options.onThrottle === 'function' ? options.onThrottle : null;
-  }
-
-  /** Un intento único, sin reintentos. */
-  async _fetchOnce(url, { method = 'GET', headers = {}, body = null, raw = false } = {}) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-    let res;
-    try {
-      res = await fetch(url, {
-        method,
-        headers,
-        // Un Buffer va tal cual: es el cuerpo de una subida a URL firmada, y
-        // pasarlo por JSON.stringify lo convertiría en el texto "{\"type\":
-        // \"Buffer\",\"data\":[...]}", que es exactamente la corrupción
-        // silenciosa que la subida directa vino a evitar.
-        body: body == null ? undefined : Buffer.isBuffer(body) ? body : JSON.stringify(body),
-        signal: controller.signal,
-      });
-    } catch (err) {
-      clearTimeout(timer);
-      if (err.name === 'AbortError') {
-        throw new ShiloError(`Timeout tras ${this.timeoutMs}ms: ${method} ${url}`, {
-          retryable: true,
-        });
-      }
-      throw new ShiloError(`Fallo de red: ${err.message}`, { retryable: true });
-    }
-    clearTimeout(timer);
-
-    // `raw`: la respuesta son bytes (un binario bajado de una URL firmada) y
-    // leerla como texto la decodificaría como UTF-8, que es destruirla. Los
-    // errores tampoco se parsean acá: con `raw` el llamador mira `res.status`.
-    if (raw) {
-      const buffer = res.ok ? Buffer.from(await res.arrayBuffer()) : null;
-      return { res, data: buffer };
-    }
-
-    const text = await res.text();
-    let data = null;
-    if (text) {
-      try {
-        data = JSON.parse(text);
-      } catch (_) {
-        data = text;
-      }
-    }
-    return { res, data };
-  }
-
-  /**
-   * `_fetchOnce` + reintentos con backoff exponencial y jitter. Un 502
-   * transitorio o un microcorte de red dejaban de forma permanente ese archivo
-   * afuera del push —y si pasaba en la fase de commit, quedaban archivos
-   * escritos sin commit que los registrara.
-   */
-  async _fetch(url, options = {}) {
-    const maxAttempts = Math.max(1, this.retries);
-    let nextDelay = 0;
-
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      const isLast = attempt === maxAttempts - 1;
-      if (attempt > 0) await sleep(nextDelay);
-
-      let result;
-      try {
-        result = await this._fetchOnce(url, options);
-      } catch (err) {
-        if (!err.retryable || isLast) throw err;
-        nextDelay = backoffDelay(attempt);
-        continue;
-      }
-
-      const { res } = result;
-      const throttled = res.status === 429;
-      if (throttled && this.onThrottle) this.onThrottle();
-
-      if ((!throttled && res.status < 500) || isLast) return result;
-
-      const hinted = retryAfterMs(res);
-      nextDelay = hinted != null ? hinted : backoffDelay(attempt);
-    }
-
-    /* istanbul ignore next — el bucle siempre sale por return o throw */
-    throw new ShiloError(`No se pudo completar la petición a ${url}`);
-  }
-
-  _errMessage(data, fallback) {
-    if (data && typeof data === 'object') {
-      if (typeof data.error === 'string') return data.error;
-      if (typeof data.message === 'string') return data.message;
-      return JSON.stringify(data);
-    }
-    if (typeof data === 'string' && data) return data;
-    return fallback;
-  }
-
-  /**
-   * Autentica contra /api/auth/login. Devuelve credenciales normalizadas.
-   */
-  async authenticate(email, password) {
-    const { res, data } = await this._fetch(`${this.baseURL}/api/auth/login`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: { email, password },
-    });
-
-    if (!res.ok) {
-      throw new ShiloError(
-        `Autenticación fallida: ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-
-    const session = data && data.data && data.data.session;
-    const user = data && data.data && data.data.user;
-    if (!session || !session.access_token) {
-      throw new ShiloError('Respuesta de login inesperada (sin session.access_token)', {
-        status: res.status,
-        body: data,
-      });
-    }
-
-    const expiresAt = new Date(Date.now() + (session.expires_in || 3600) * 1000).toISOString();
-    return {
-      jwt: session.access_token,
-      refreshToken: session.refresh_token || null,
-      expiresAt,
-      user: user ? { id: user.id, email: user.email } : null,
-    };
-  }
-
-  /**
-   * Refresca el JWT con el refresh_token vía Supabase. Requiere supabaseUrl +
-   * supabaseAnonKey configurados; si no, lanza para que el caller pida re-login.
-   */
-  async refreshToken(refreshToken) {
-    if (!this.supabaseUrl || !this.supabaseAnonKey) {
-      throw new ShiloError(
-        'Refresh no configurado (falta supabaseUrl/anonKey). Ejecutá "shilo login" de nuevo.'
-      );
-    }
-    const { res, data } = await this._fetch(
-      `${this.supabaseUrl.replace(/\/+$/, '')}/auth/v1/token?grant_type=refresh_token`,
-      {
-        method: 'POST',
-        headers: {
-          apikey: this.supabaseAnonKey,
-          'Content-Type': 'application/json',
-        },
-        body: { refresh_token: refreshToken },
-      }
-    );
-    if (!res.ok || !data || !data.access_token) {
-      throw new ShiloError('No se pudo refrescar el token. Re-autenticación requerida.', {
-        status: res.status,
-        body: data,
-      });
-    }
-    const expiresAt = new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString();
-    return {
-      jwt: data.access_token,
-      refreshToken: data.refresh_token || refreshToken,
-      expiresAt,
-    };
-  }
-
-  /**
-   * Devuelve credenciales con JWT válido, refrescando si faltan <5min.
-   * Si el refresh no está disponible/falla, propaga para que el CLI pida login.
-   *
-   * Un PAT no tiene refresh ni expiración local: la validez la decide el
-   * servidor en cada request, así que se devuelve tal cual.
-   */
-  async ensureValidToken(credentials) {
-    if (credentials && credentials.kind === 'pat') return credentials;
-
-    if (!credentials || !credentials.jwt) {
-      throw new ShiloError('No hay sesión. Ejecutá "shilo login".');
-    }
-    const msLeft = new Date(credentials.expiresAt).getTime() - Date.now();
-    if (msLeft >= 5 * 60 * 1000) return credentials;
-
-    if (!credentials.refreshToken) {
-      throw new ShiloError('Sesión expirada. Ejecutá "shilo login" de nuevo.');
-    }
-    const fresh = await this.refreshToken(credentials.refreshToken);
-    return { ...credentials, ...fresh };
-  }
-
-  /**
-   * Verifica que unas credenciales sean aceptadas por el servidor, listando los
-   * proyectos del usuario. Sirve tanto para JWT como para PAT.
-   * Devuelve `{ ok: <bool>, status, error }` — no lanza por credenciales malas.
-   */
-  async verifyCredentials(credentials) {
-    const headers = { Authorization: `Bearer ${credentials.jwt}` };
-    const { res, data } = await this._fetch(`${this.baseURL}/api/projects`, { headers });
-    if (res.ok) return { ok: true, status: res.status, error: null };
-    return {
-      ok: false,
-      status: res.status,
-      error: this._errMessage(data, `HTTP ${res.status}`),
-    };
-  }
-
-  // ---------------------------------------------------------------------------
-  // Helpers de archivos
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Codifica una ruta de repo (segmentos separados por `/`) para la URL,
-   * escapando cada segmento pero conservando los separadores. Los nombres
-   * válidos en Shilo pueden incluir `[ ] ( ) @`, que conviene escapar.
-   */
-  _encodePath(repoPath) {
-    if (!repoPath) return '';
-    return repoPath
-      .split('/')
-      .filter(Boolean)
-      .map((seg) => encodeURIComponent(seg))
-      .join('/');
-  }
-
-  _fileUrl(projectId, repoPath = '') {
-    const enc = this._encodePath(repoPath);
-    return enc
-      ? `${this.baseURL}/api/files/${projectId}/${enc}`
-      : `${this.baseURL}/api/files/${projectId}`;
-  }
-
-  async _authFetch(url, credentials, { method = 'GET', body = null } = {}) {
-    const validCreds = await this.ensureValidToken(credentials);
-    const headers = { Authorization: `Bearer ${validCreds.jwt}` };
-    if (body != null && !Buffer.isBuffer(body)) headers['Content-Type'] = 'application/json';
-    const { res, data } = await this._fetch(url, { method, headers, body });
-    return { res, data, credentials: validCreds };
-  }
-
-  /**
-   * Lista el contenido directo de una carpeta (no recursa). Raíz responde
-   * `{ files }`, una carpeta responde `{ folder, files }`.
-   * Devuelve `{ files: [...], credentials }`.
-   */
-  async listFiles(projectId, credentials, folderPath = '') {
-    const url = this._fileUrl(projectId, folderPath);
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudieron listar archivos: ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const files = data && Array.isArray(data.files) ? data.files : Array.isArray(data) ? data : [];
-    return { files, credentials: creds };
-  }
-
-  /**
-   * Obtiene la metadata de un archivo/carpeta por ruta SIN descargar contenido.
-   * Devuelve `{ file: <obj|null>, exists: <bool>, credentials }`.
-   * Un 404 no es error: significa que la ruta no existe todavía (archivo nuevo).
-   */
-  async getFileMeta(projectId, filePath, credentials) {
-    const url = this._fileUrl(projectId, filePath);
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
-    if (res.status === 404) {
-      return { file: null, exists: false, credentials: creds };
-    }
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo consultar "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const file = data && data.file ? data.file : data;
-    return { file: file || null, exists: !!file, credentials: creds };
-  }
-
-  /**
-   * Lee metadata + contenido de un archivo (`?content=true`).
-   * Devuelve `{ file: { ...meta, content }, credentials }`.
-   */
-  async readFile(projectId, filePath, credentials) {
-    const url = `${this._fileUrl(projectId, filePath)}?content=true`;
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo leer "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const file = data && data.file ? data.file : {};
-    const content = data && data.content !== undefined ? data.content : null;
-    // Un binario no viene con contenido: viene con una URL firmada para bajarlo
-    // directo de Storage (ver `downloadBinary`). Los dos campos se pegan al
-    // `file` para que el llamador decida con un solo objeto en la mano.
-    return {
-      file: {
-        ...file,
-        content,
-        is_binary: Boolean(data && data.is_binary),
-        download_url: (data && data.download_url) || null,
-      },
-      credentials: creds,
-    };
-  }
-
-  /**
-   * Crea un archivo nuevo (POST a la carpeta padre). Idempotente en el server:
-   * si ya existe, responde 409 con el objeto existente. Aquí tratamos el 409
-   * como "ya existía" y devolvemos `{ file, created: false }` para que el caller
-   * decida (normalmente, hacer un PUT).
-   * Devuelve `{ file, created: <bool>, credentials }`.
-   */
-  async createFile(projectId, filePath, content, mimeType, credentials) {
-    const parts = filePath.split('/').filter(Boolean);
-    const fileName = parts.pop();
-    const parentPath = parts.join('/');
-    const url = this._fileUrl(projectId, parentPath);
-
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
-      method: 'POST',
-      body: { name: fileName, type: 'file', content, mimeType },
-    });
-
-    if (res.status === 409) {
-      const existing = (data && (data.file || data.folder)) || null;
-      return { file: existing, created: false, credentials: creds };
-    }
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo crear "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const file = (data && (data.file || data)) || null;
-    return { file, created: true, credentials: creds };
-  }
-
-  /**
-   * Actualiza el contenido de un archivo existente (PUT). Devuelve el archivo
-   * con su NUEVO `storage_path`. `{ file, credentials }`.
-   */
-  async writeFile(projectId, filePath, content, mimeType, credentials) {
-    const url = this._fileUrl(projectId, filePath);
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
-      method: 'PUT',
-      body: { content, mimeType },
-    });
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo actualizar "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const file = (data && (data.file || data)) || null;
-    return { file, credentials: creds };
-  }
-
-  /**
-   * Escribe varios archivos en una sola llamada (`POST /api/files/:id/batch`).
-   * Crea las carpetas intermedias por su cuenta, así que no hace falta un
-   * `ensurePath` previo.
-   *
-   * `files`: [{ path, content, mimeType? }] — máximo 100 y 5 MB por lote.
-   *
-   * El endpoint responde 200 aunque algunos archivos fallen: el resultado viene
-   * POR ARCHIVO, en el mismo orden que se mandó. Los `ok:true` traen
-   * `file.previous_storage_path`, que es lo que después pide el commit.
-   * Devuelve `{ results, summary, credentials }`.
-   *
-   * Un servidor viejo (sin el endpoint) responde 404/405: se marca en el error
-   * con `notSupported` para que el caller pueda caer al camino de a un archivo.
-   */
-  async writeBatch(projectId, files, credentials) {
-    const url = `${this.baseURL}/api/files/${projectId}/batch`;
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
-      method: 'POST',
-      body: { files },
-    });
-
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo escribir el lote: ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data, notSupported: res.status === 404 || res.status === 405 }
-      );
-    }
-
-    const results = data && Array.isArray(data.results) ? data.results : [];
-    const summary = (data && data.summary) || {
-      total: results.length,
-      succeeded: results.filter((r) => r && r.ok).length,
-      failed: results.filter((r) => r && !r.ok).length,
-    };
-    return { results, summary, credentials: creds };
-  }
-
-  /**
-   * Baja los bytes de una URL firmada. Devuelve un Buffer.
-   *
-   * No lleva `Authorization`: la firma ES la autorización, y mandar el JWT a una
-   * URL de Storage sería filtrarlo a un origen que no lo necesita.
-   */
-  async downloadBinary(signedUrl) {
-    const { res, data } = await this._fetch(signedUrl, { method: 'GET', raw: true });
-    if (!res.ok || !data) {
-      throw new ShiloError(`No se pudo descargar el contenido: HTTP ${res.status}`, {
-        status: res.status,
-      });
-    }
-    return data;
-  }
-
-  /**
-   * Sube un archivo binario: URL firmada, tres pasos.
-   *
-   * El contenido NO puede viajar por `writeBatch` ni por `writeFile`: esos
-   * mandan el archivo como string dentro de un JSON, y el backend lo hashea con
-   * `Buffer.from(content, 'utf8')`. Un binario se corrompe ahí, ANTES de
-   * hashearse, y el grafo registra el resultado corrupto como válido — no hay
-   * verificador que lo note, porque para el motor no pasó nada raro. Por eso el
-   * byte va directo a Storage y nunca entra en un payload JSON.
-   *
-   * Los tres pasos:
-   *   1. `begin`  — el servidor firma una URL contra la ruta por contenido del
-   *                  blob. Si ese contenido ya está en el proyecto responde
-   *                  `exists: true` y no hay nada que transferir: el archivo ya
-   *                  está ahí, aunque sea con otro nombre.
-   *   2. PUT      — los bytes, directo a Storage. No pasa por la función
-   *                  serverless, así que el límite de payload de Vercel deja de
-   *                  aplicar.
-   *   3. `commit` — el servidor verifica y apunta la fila de `files` al blob.
-   *
-   * `entry`: { path, buffer, mimeType }.
-   * Devuelve `{ result, uploaded, credentials }`, donde `result` tiene la misma
-   * forma que un elemento de `writeBatch` (`ok`, `action`, `file`) y `uploaded`
-   * dice si hubo bytes en el aire.
-   */
-  async uploadBinary(projectId, entry, credentials) {
-    const url = `${this.baseURL}/api/files/${projectId}/direct`;
-    const payload = {
-      path: entry.path,
-      size: entry.buffer.length,
-      content_hash: entry.contentHash,
-      mime_type: entry.mimeType || 'application/octet-stream',
-    };
-
-    const begun = await this._authFetch(url, credentials, {
-      method: 'POST',
-      body: { action: 'begin', ...payload },
-    });
-
-    if (!begun.res.ok) {
-      throw new ShiloError(
-        `No se pudo preparar la subida de "${entry.path}": ${this._errMessage(begun.data, `HTTP ${begun.res.status}`)}`,
-        {
-          status: begun.res.status,
-          body: begun.data,
-          notSupported: begun.res.status === 404 || begun.res.status === 405,
-        }
-      );
-    }
-
-    let uploaded = false;
-    const upload = begun.data && begun.data.upload;
-
-    if (upload && upload.url) {
-      const { res } = await this._fetch(upload.url, {
-        method: 'PUT',
-        headers: {
-          'Content-Type': entry.mimeType || 'application/octet-stream',
-          // `x-upsert: false` es el default de una URL firmada de subida y se
-          // deja explícito: si el objeto ya existiera, pisarlo reemplazaría el
-          // contenido de un blob conservando su identidad, que es justo el
-          // ataque que el direccionamiento por contenido tiene que impedir.
-          'x-upsert': 'false',
-        },
-        body: entry.buffer,
-      });
-
-      if (!res.ok) {
-        throw new ShiloError(
-          `No se pudo subir el contenido de "${entry.path}": HTTP ${res.status}`,
-          { status: res.status }
-        );
-      }
-      uploaded = true;
-    }
-
-    const done = await this._authFetch(url, begun.credentials, {
-      method: 'POST',
-      body: { action: 'commit', ...payload },
-    });
-
-    if (!done.res.ok) {
-      throw new ShiloError(
-        `No se pudo registrar "${entry.path}": ${this._errMessage(done.data, `HTTP ${done.res.status}`)}`,
-        { status: done.res.status, body: done.data }
-      );
-    }
-
-    return { result: done.data, uploaded, credentials: done.credentials };
-  }
-
-  /**
-   * Crea una carpeta bajo `parentPath` (vacío = raíz). Un 409 significa que ya
-   * existe: no es fatal, devolvemos `{ folder, existed: true }`.
-   * `{ folder, existed: <bool>, credentials }`.
-   */
-  async createFolder(projectId, folderName, parentPath = '', credentials) {
-    const url = this._fileUrl(projectId, parentPath);
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
-      method: 'POST',
-      body: { name: folderName, type: 'folder' },
-    });
-    if (res.status === 409) {
-      const existing = (data && (data.folder || data.file)) || { name: folderName };
-      return { folder: existing, existed: true, credentials: creds };
-    }
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo crear la carpeta "${folderName}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const folder = (data && (data.file || data)) || null;
-    return { folder, existed: false, credentials: creds };
-  }
-
-  /**
-   * Asegura que existan todas las carpetas del path de un archivo.
-   * Estrategia anti-duplicados: Shilo puede no devolver 409 fiable, así que
-   * listamos el padre antes de crear y reutilizamos la carpeta si ya existe.
-   * `ensuredCache` (Set de rutas completas) evita re-listar dentro de una corrida.
-   * Devuelve las credenciales (posiblemente refrescadas).
-   */
-  async ensurePath(projectId, filePath, credentials, ensuredCache = null) {
-    const parts = filePath.split('/').filter(Boolean);
-    parts.pop(); // quitar el nombre del archivo
-    if (parts.length === 0) return credentials;
-
-    let currentCreds = credentials;
-    let parentPath = '';
-
-    for (const folderName of parts) {
-      const fullPath = parentPath ? `${parentPath}/${folderName}` : folderName;
-
-      if (ensuredCache && ensuredCache.has(fullPath)) {
-        parentPath = fullPath;
-        continue;
-      }
-
-      let exists = false;
-      try {
-        const listResult = await this.listFiles(projectId, currentCreds, parentPath);
-        currentCreds = listResult.credentials;
-        exists = listResult.files.some((e) => e && e.type === 'folder' && e.name === folderName);
-      } catch (_) {
-        // El padre puede no existir aún: dejamos que createFolder lo cree.
-        exists = false;
-      }
-
-      if (!exists) {
-        const result = await this.createFolder(projectId, folderName, parentPath, currentCreds);
-        currentCreds = result.credentials;
-      }
-
-      if (ensuredCache) ensuredCache.add(fullPath);
-      parentPath = fullPath;
-    }
-
-    return currentCreds;
-  }
-
-  /**
-   * Lista el historial de commits del proyecto (más nuevo primero).
-   * `includeFiles` pide además los `commit_files` de cada commit, que es lo que
-   * permite saber quién tocó cada archivo por última vez.
-   * Devuelve `{ commits, hasMore, credentials }`.
-   */
-  async listCommits(projectId, credentials, { limit = 20, page = 1, includeFiles = false } = {}) {
-    const params = new URLSearchParams({ limit: String(limit), page: String(page) });
-    if (includeFiles) params.set('include', 'files');
-    const url = `${this.baseURL}/api/commits/${projectId}?${params.toString()}`;
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo listar el historial: ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const commits = data && Array.isArray(data.commits) ? data.commits : [];
-    const hasMore = !!(data && data.pagination && data.pagination.hasMore);
-    return { commits, hasMore, credentials: creds };
-  }
-
-  /**
-   * Crea un commit con la lista de cambios de archivos (máx 100 por lote).
-   * `changes`: [{ file_id, action, previous_storage_path?, new_storage_path? }].
-   * Devuelve `{ commit, credentials }`.
-   */
-  async createCommit(projectId, message, changes, credentials) {
-    const url = `${this.baseURL}/api/commits/${projectId}`;
-    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
-      method: 'POST',
-      body: { message, files: changes },
-    });
-    if (!res.ok) {
-      throw new ShiloError(
-        `No se pudo crear el commit: ${this._errMessage(data, `HTTP ${res.status}`)}`,
-        { status: res.status, body: data }
-      );
-    }
-    const commit = (data && data.commit) || data;
-    return { commit, credentials: creds };
-  }
-}
-
-module.exports = { ShiloClient, ShiloError };
+'use strict';
+
+/**
+ * Cliente HTTP para la API de Shilo. Portado del ShiloClient de
+ * Bnei-Yerushalaim-Cloud, adaptado a `fetch` nativo (Node >=18, cero deps).
+ *
+ * Autenticación (Fase 1):
+ *   - authenticate(email, password)
+ *   - refreshToken(refreshToken)         (requiere supabaseUrl + anonKey)
+ *   - ensureValidToken(credentials)
+ *
+ * Archivos y commits (Fase 2):
+ *   - listFiles / getFileMeta / readFile
+ *   - createFile / writeFile / writeBatch / createFolder / ensurePath
+ *   - createCommit
+ *
+ * Todos los métodos de red toman `credentials` y devuelven `{ ..., credentials }`
+ * con las credenciales posiblemente refrescadas, para que el caller las persista.
+ */
+
+const { leerArbolShilo } = require('./gitobjects');
+
+const DEFAULT_BASE_URL = 'https://www.shilo.city';
+const DEFAULT_TIMEOUT_MS = 45000;
+
+// Reintentos: sólo para fallos que pueden desaparecer solos (red, timeout, 429,
+// 5xx). Un 4xx que no sea 429 es un error del cliente —ruta inválida, permisos,
+// body mal formado— y repetirlo sólo gasta tiempo.
+const DEFAULT_RETRIES = 3;
+const RETRY_BASE_MS = 250;
+const RETRY_MAX_MS = 8000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Backoff exponencial con jitter completo. El jitter importa: sin él, N
+ * requests que chocan con el mismo 429 reintentan todos en el mismo
+ * milisegundo y vuelven a chocar.
+ */
+function backoffDelay(attempt) {
+  const ceiling = Math.min(RETRY_BASE_MS * Math.pow(4, attempt), RETRY_MAX_MS);
+  return Math.round(ceiling * (0.5 + Math.random() * 0.5));
+}
+
+/** Lee `Retry-After` (segundos o fecha HTTP). Devuelve ms, o null. */
+function retryAfterMs(res) {
+  const raw = res && res.headers && res.headers.get && res.headers.get('retry-after');
+  if (!raw) return null;
+  const secs = Number(raw);
+  if (Number.isFinite(secs)) return Math.max(0, Math.min(secs * 1000, 60000));
+  const when = Date.parse(raw);
+  if (!Number.isNaN(when)) return Math.max(0, Math.min(when - Date.now(), 60000));
+  return null;
+}
+
+/**
+ * El ápex https://shilo.city responde 307 hacia https://www.shilo.city. Como
+ * `fetch` sigue redirects pero descarta el header Authorization al cruzar de
+ * origen, apuntar al ápex haría fallar con 401 todo lo autenticado (push, pull,
+ * projects). Normalizamos a www para que nunca ocurra ese salto.
+ */
+function normalizeBaseURL(url) {
+  const clean = String(url).replace(/\/+$/, '');
+  return clean.replace(/^(https?:\/\/)shilo\.city(?=$|\/)/i, '$1www.shilo.city');
+}
+
+class ShiloError extends Error {
+  constructor(message, { status = null, body = null, retryable = false, notSupported = false } = {}) {
+    super(message);
+    this.name = 'ShiloError';
+    this.status = status;
+    this.body = body;
+    this.retryable = retryable;
+    // El servidor no conoce el endpoint (deploy viejo): el caller puede usar
+    // el camino alternativo en vez de abortar.
+    this.notSupported = notSupported;
+  }
+}
+
+class ShiloClient {
+  constructor(options = {}) {
+    this.baseURL = normalizeBaseURL(options.baseURL || DEFAULT_BASE_URL);
+    this.timeoutMs = Number(options.timeoutMs) || DEFAULT_TIMEOUT_MS;
+    // Opcionales: habilitan refresh de token sin re-login.
+    this.supabaseUrl = options.supabaseUrl || null;
+    this.supabaseAnonKey = options.supabaseAnonKey || null;
+    this.retries = options.retries != null ? Number(options.retries) : DEFAULT_RETRIES;
+    // Se avisa de cada 429 para que el caller pueda bajar la concurrencia en vez
+    // de seguir martillando al servidor con la misma cadencia.
+    this.onThrottle = typeof options.onThrottle === 'function' ? options.onThrottle : null;
+  }
+
+  /** Un intento único, sin reintentos. */
+  async _fetchOnce(url, { method = 'GET', headers = {}, body = null, raw = false } = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        // Un Buffer va tal cual: es el cuerpo de una subida a URL firmada, y
+        // pasarlo por JSON.stringify lo convertiría en el texto "{\"type\":
+        // \"Buffer\",\"data\":[...]}", que es exactamente la corrupción
+        // silenciosa que la subida directa vino a evitar.
+        body: body == null ? undefined : Buffer.isBuffer(body) ? body : JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err.name === 'AbortError') {
+        throw new ShiloError(`Timeout tras ${this.timeoutMs}ms: ${method} ${url}`, {
+          retryable: true,
+        });
+      }
+      throw new ShiloError(`Fallo de red: ${err.message}`, { retryable: true });
+    }
+    clearTimeout(timer);
+
+    // `raw`: la respuesta son bytes (un binario bajado de una URL firmada) y
+    // leerla como texto la decodificaría como UTF-8, que es destruirla. Los
+    // errores tampoco se parsean acá: con `raw` el llamador mira `res.status`.
+    if (raw) {
+      const buffer = res.ok ? Buffer.from(await res.arrayBuffer()) : null;
+      return { res, data: buffer };
+    }
+
+    const text = await res.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch (_) {
+        data = text;
+      }
+    }
+    return { res, data };
+  }
+
+  /**
+   * `_fetchOnce` + reintentos con backoff exponencial y jitter. Un 502
+   * transitorio o un microcorte de red dejaban de forma permanente ese archivo
+   * afuera del push —y si pasaba en la fase de commit, quedaban archivos
+   * escritos sin commit que los registrara.
+   */
+  async _fetch(url, options = {}) {
+    const maxAttempts = Math.max(1, this.retries);
+    let nextDelay = 0;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const isLast = attempt === maxAttempts - 1;
+      if (attempt > 0) await sleep(nextDelay);
+
+      let result;
+      try {
+        result = await this._fetchOnce(url, options);
+      } catch (err) {
+        if (!err.retryable || isLast) throw err;
+        nextDelay = backoffDelay(attempt);
+        continue;
+      }
+
+      const { res } = result;
+      const throttled = res.status === 429;
+      if (throttled && this.onThrottle) this.onThrottle();
+
+      if ((!throttled && res.status < 500) || isLast) return result;
+
+      const hinted = retryAfterMs(res);
+      nextDelay = hinted != null ? hinted : backoffDelay(attempt);
+    }
+
+    /* istanbul ignore next — el bucle siempre sale por return o throw */
+    throw new ShiloError(`No se pudo completar la petición a ${url}`);
+  }
+
+  _errMessage(data, fallback) {
+    if (data && typeof data === 'object') {
+      if (typeof data.error === 'string') return data.error;
+      if (typeof data.message === 'string') return data.message;
+      return JSON.stringify(data);
+    }
+    if (typeof data === 'string' && data) return data;
+    return fallback;
+  }
+
+  /**
+   * Autentica contra /api/auth/login. Devuelve credenciales normalizadas.
+   */
+  async authenticate(email, password) {
+    const { res, data } = await this._fetch(`${this.baseURL}/api/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: { email, password },
+    });
+
+    if (!res.ok) {
+      throw new ShiloError(
+        `Autenticación fallida: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+
+    const session = data && data.data && data.data.session;
+    const user = data && data.data && data.data.user;
+    if (!session || !session.access_token) {
+      throw new ShiloError('Respuesta de login inesperada (sin session.access_token)', {
+        status: res.status,
+        body: data,
+      });
+    }
+
+    const expiresAt = new Date(Date.now() + (session.expires_in || 3600) * 1000).toISOString();
+    return {
+      jwt: session.access_token,
+      refreshToken: session.refresh_token || null,
+      expiresAt,
+      user: user ? { id: user.id, email: user.email } : null,
+    };
+  }
+
+  /**
+   * Refresca el JWT con el refresh_token vía Supabase. Requiere supabaseUrl +
+   * supabaseAnonKey configurados; si no, lanza para que el caller pida re-login.
+   */
+  async refreshToken(refreshToken) {
+    if (!this.supabaseUrl || !this.supabaseAnonKey) {
+      throw new ShiloError(
+        'Refresh no configurado (falta supabaseUrl/anonKey). Ejecutá "shilo login" de nuevo.'
+      );
+    }
+    const { res, data } = await this._fetch(
+      `${this.supabaseUrl.replace(/\/+$/, '')}/auth/v1/token?grant_type=refresh_token`,
+      {
+        method: 'POST',
+        headers: {
+          apikey: this.supabaseAnonKey,
+          'Content-Type': 'application/json',
+        },
+        body: { refresh_token: refreshToken },
+      }
+    );
+    if (!res.ok || !data || !data.access_token) {
+      throw new ShiloError('No se pudo refrescar el token. Re-autenticación requerida.', {
+        status: res.status,
+        body: data,
+      });
+    }
+    const expiresAt = new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString();
+    return {
+      jwt: data.access_token,
+      refreshToken: data.refresh_token || refreshToken,
+      expiresAt,
+    };
+  }
+
+  /**
+   * Devuelve credenciales con JWT válido, refrescando si faltan <5min.
+   * Si el refresh no está disponible/falla, propaga para que el CLI pida login.
+   *
+   * Un PAT no tiene refresh ni expiración local: la validez la decide el
+   * servidor en cada request, así que se devuelve tal cual.
+   */
+  async ensureValidToken(credentials) {
+    if (credentials && credentials.kind === 'pat') return credentials;
+
+    if (!credentials || !credentials.jwt) {
+      throw new ShiloError('No hay sesión. Ejecutá "shilo login".');
+    }
+    const msLeft = new Date(credentials.expiresAt).getTime() - Date.now();
+    if (msLeft >= 5 * 60 * 1000) return credentials;
+
+    if (!credentials.refreshToken) {
+      throw new ShiloError('Sesión expirada. Ejecutá "shilo login" de nuevo.');
+    }
+    const fresh = await this.refreshToken(credentials.refreshToken);
+    return { ...credentials, ...fresh };
+  }
+
+  /**
+   * Verifica que unas credenciales sean aceptadas por el servidor, listando los
+   * proyectos del usuario. Sirve tanto para JWT como para PAT.
+   * Devuelve `{ ok: <bool>, status, error }` — no lanza por credenciales malas.
+   */
+  async verifyCredentials(credentials) {
+    const headers = { Authorization: `Bearer ${credentials.jwt}` };
+    const { res, data } = await this._fetch(`${this.baseURL}/api/projects`, { headers });
+    if (res.ok) return { ok: true, status: res.status, error: null };
+    return {
+      ok: false,
+      status: res.status,
+      error: this._errMessage(data, `HTTP ${res.status}`),
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helpers de archivos
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Codifica una ruta de repo (segmentos separados por `/`) para la URL,
+   * escapando cada segmento pero conservando los separadores. Los nombres
+   * válidos en Shilo pueden incluir `[ ] ( ) @`, que conviene escapar.
+   */
+  _encodePath(repoPath) {
+    if (!repoPath) return '';
+    return repoPath
+      .split('/')
+      .filter(Boolean)
+      .map((seg) => encodeURIComponent(seg))
+      .join('/');
+  }
+
+  _fileUrl(projectId, repoPath = '') {
+    const enc = this._encodePath(repoPath);
+    return enc
+      ? `${this.baseURL}/api/files/${projectId}/${enc}`
+      : `${this.baseURL}/api/files/${projectId}`;
+  }
+
+  async _authFetch(url, credentials, { method = 'GET', body = null } = {}) {
+    const validCreds = await this.ensureValidToken(credentials);
+    const headers = { Authorization: `Bearer ${validCreds.jwt}` };
+    if (body != null && !Buffer.isBuffer(body)) headers['Content-Type'] = 'application/json';
+    const { res, data } = await this._fetch(url, { method, headers, body });
+    return { res, data, credentials: validCreds };
+  }
+
+  /**
+   * Lista el contenido directo de una carpeta (no recursa). Raíz responde
+   * `{ files }`, una carpeta responde `{ folder, files }`.
+   * Devuelve `{ files: [...], credentials }`.
+   */
+  async listFiles(projectId, credentials, folderPath = '') {
+    const url = this._fileUrl(projectId, folderPath);
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudieron listar archivos: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const files = data && Array.isArray(data.files) ? data.files : Array.isArray(data) ? data : [];
+    return { files, credentials: creds };
+  }
+
+  /**
+   * Obtiene la metadata de un archivo/carpeta por ruta SIN descargar contenido.
+   * Devuelve `{ file: <obj|null>, exists: <bool>, credentials }`.
+   * Un 404 no es error: significa que la ruta no existe todavía (archivo nuevo).
+   */
+  async getFileMeta(projectId, filePath, credentials) {
+    const url = this._fileUrl(projectId, filePath);
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
+    if (res.status === 404) {
+      return { file: null, exists: false, credentials: creds };
+    }
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo consultar "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const file = data && data.file ? data.file : data;
+    return { file: file || null, exists: !!file, credentials: creds };
+  }
+
+  /**
+   * Lee metadata + contenido de un archivo (`?content=true`).
+   * Devuelve `{ file: { ...meta, content }, credentials }`.
+   */
+  async readFile(projectId, filePath, credentials) {
+    const url = `${this._fileUrl(projectId, filePath)}?content=true`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo leer "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const file = data && data.file ? data.file : {};
+    const content = data && data.content !== undefined ? data.content : null;
+    // Un binario no viene con contenido: viene con una URL firmada para bajarlo
+    // directo de Storage (ver `downloadBinary`). Los dos campos se pegan al
+    // `file` para que el llamador decida con un solo objeto en la mano.
+    return {
+      file: {
+        ...file,
+        content,
+        is_binary: Boolean(data && data.is_binary),
+        download_url: (data && data.download_url) || null,
+      },
+      credentials: creds,
+    };
+  }
+
+  /**
+   * Crea un archivo nuevo (POST a la carpeta padre). Idempotente en el server:
+   * si ya existe, responde 409 con el objeto existente. Aquí tratamos el 409
+   * como "ya existía" y devolvemos `{ file, created: false }` para que el caller
+   * decida (normalmente, hacer un PUT).
+   * Devuelve `{ file, created: <bool>, credentials }`.
+   */
+  async createFile(projectId, filePath, content, mimeType, credentials) {
+    const parts = filePath.split('/').filter(Boolean);
+    const fileName = parts.pop();
+    const parentPath = parts.join('/');
+    const url = this._fileUrl(projectId, parentPath);
+
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { name: fileName, type: 'file', content, mimeType },
+    });
+
+    if (res.status === 409) {
+      const existing = (data && (data.file || data.folder)) || null;
+      return { file: existing, created: false, credentials: creds };
+    }
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo crear "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const file = (data && (data.file || data)) || null;
+    return { file, created: true, credentials: creds };
+  }
+
+  /**
+   * Actualiza el contenido de un archivo existente (PUT). Devuelve el archivo
+   * con su NUEVO `storage_path`. `{ file, credentials }`.
+   */
+  async writeFile(projectId, filePath, content, mimeType, credentials) {
+    const url = this._fileUrl(projectId, filePath);
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'PUT',
+      body: { content, mimeType },
+    });
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo actualizar "${filePath}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const file = (data && (data.file || data)) || null;
+    return { file, credentials: creds };
+  }
+
+  /**
+   * Escribe varios archivos en una sola llamada (`POST /api/files/:id/batch`).
+   * Crea las carpetas intermedias por su cuenta, así que no hace falta un
+   * `ensurePath` previo.
+   *
+   * `files`: [{ path, content, mimeType? }] — máximo 100 y 5 MB por lote.
+   *
+   * El endpoint responde 200 aunque algunos archivos fallen: el resultado viene
+   * POR ARCHIVO, en el mismo orden que se mandó. Los `ok:true` traen
+   * `file.previous_storage_path`, que es lo que después pide el commit.
+   * Devuelve `{ results, summary, credentials }`.
+   *
+   * Un servidor viejo (sin el endpoint) responde 404/405: se marca en el error
+   * con `notSupported` para que el caller pueda caer al camino de a un archivo.
+   */
+  async writeBatch(projectId, files, credentials) {
+    const url = `${this.baseURL}/api/files/${projectId}/batch`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { files },
+    });
+
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo escribir el lote: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data, notSupported: res.status === 404 || res.status === 405 }
+      );
+    }
+
+    const results = data && Array.isArray(data.results) ? data.results : [];
+    const summary = (data && data.summary) || {
+      total: results.length,
+      succeeded: results.filter((r) => r && r.ok).length,
+      failed: results.filter((r) => r && !r.ok).length,
+    };
+    return { results, summary, credentials: creds };
+  }
+
+  /**
+   * Baja los bytes de una URL firmada. Devuelve un Buffer.
+   *
+   * No lleva `Authorization`: la firma ES la autorización, y mandar el JWT a una
+   * URL de Storage sería filtrarlo a un origen que no lo necesita.
+   */
+  async downloadBinary(signedUrl) {
+    const { res, data } = await this._fetch(signedUrl, { method: 'GET', raw: true });
+    if (!res.ok || !data) {
+      throw new ShiloError(`No se pudo descargar el contenido: HTTP ${res.status}`, {
+        status: res.status,
+      });
+    }
+    return data;
+  }
+
+  /**
+   * Sube un archivo binario: URL firmada, tres pasos.
+   *
+   * El contenido NO puede viajar por `writeBatch` ni por `writeFile`: esos
+   * mandan el archivo como string dentro de un JSON, y el backend lo hashea con
+   * `Buffer.from(content, 'utf8')`. Un binario se corrompe ahí, ANTES de
+   * hashearse, y el grafo registra el resultado corrupto como válido — no hay
+   * verificador que lo note, porque para el motor no pasó nada raro. Por eso el
+   * byte va directo a Storage y nunca entra en un payload JSON.
+   *
+   * Los tres pasos:
+   *   1. `begin`  — el servidor firma una URL contra la ruta por contenido del
+   *                  blob. Si ese contenido ya está en el proyecto responde
+   *                  `exists: true` y no hay nada que transferir: el archivo ya
+   *                  está ahí, aunque sea con otro nombre.
+   *   2. PUT      — los bytes, directo a Storage. No pasa por la función
+   *                  serverless, así que el límite de payload de Vercel deja de
+   *                  aplicar.
+   *   3. `commit` — el servidor verifica y apunta la fila de `files` al blob.
+   *
+   * `entry`: { path, buffer, mimeType }.
+   * Devuelve `{ result, uploaded, credentials }`, donde `result` tiene la misma
+   * forma que un elemento de `writeBatch` (`ok`, `action`, `file`) y `uploaded`
+   * dice si hubo bytes en el aire.
+   */
+  async uploadBinary(projectId, entry, credentials) {
+    const staged = await this._stageBlob(projectId, entry, credentials);
+    const done = await this._authFetch(staged.url, staged.credentials, {
+      method: 'POST',
+      body: { action: 'commit', ...staged.payload },
+    });
+
+    if (!done.res.ok) {
+      throw new ShiloError(
+        `No se pudo registrar "${entry.path}": ${this._errMessage(done.data, `HTTP ${done.res.status}`)}`,
+        { status: done.res.status, body: done.data }
+      );
+    }
+
+    return { result: done.data, uploaded: staged.uploaded, credentials: done.credentials };
+  }
+
+  /**
+   * Deja el contenido de un archivo en el proyecto SIN tocar la versión actual:
+   * los mismos pasos que `uploadBinary` pero el tercero es `register`, que
+   * verifica e inventaria el blob y no escribe ninguna fila de `files`. Es
+   * como un binario (o un texto demasiado grande para ir inline) entra a una
+   * propuesta: por su oid.
+   *
+   * Devuelve `{ oid, uploaded, credentials }`.
+   */
+  async registerBlob(projectId, entry, credentials) {
+    const staged = await this._stageBlob(projectId, entry, credentials);
+    const done = await this._authFetch(staged.url, staged.credentials, {
+      method: 'POST',
+      body: { action: 'register', ...staged.payload },
+    });
+
+    if (!done.res.ok) {
+      throw new ShiloError(
+        `No se pudo registrar el contenido de "${entry.path}": ${this._errMessage(done.data, `HTTP ${done.res.status}`)}`,
+        {
+          status: done.res.status,
+          body: done.data,
+          notSupported: done.res.status === 404 || done.res.status === 405,
+        }
+      );
+    }
+
+    return {
+      oid: (done.data && done.data.oid) || entry.contentHash,
+      uploaded: staged.uploaded,
+      credentials: done.credentials,
+    };
+  }
+
+  /** Pasos 1 y 2 de la subida directa: `begin` y, si hace falta, el PUT. */
+  async _stageBlob(projectId, entry, credentials) {
+    const url = `${this.baseURL}/api/files/${projectId}/direct`;
+    const payload = {
+      path: entry.path,
+      size: entry.buffer.length,
+      content_hash: entry.contentHash,
+      mime_type: entry.mimeType || 'application/octet-stream',
+    };
+
+    const begun = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { action: 'begin', ...payload },
+    });
+
+    if (!begun.res.ok) {
+      throw new ShiloError(
+        `No se pudo preparar la subida de "${entry.path}": ${this._errMessage(begun.data, `HTTP ${begun.res.status}`)}`,
+        {
+          status: begun.res.status,
+          body: begun.data,
+          notSupported: begun.res.status === 404 || begun.res.status === 405,
+        }
+      );
+    }
+
+    let uploaded = false;
+    const upload = begun.data && begun.data.upload;
+
+    if (upload && upload.url) {
+      const { res } = await this._fetch(upload.url, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': entry.mimeType || 'application/octet-stream',
+          // `x-upsert: false` es el default de una URL firmada de subida y se
+          // deja explícito: si el objeto ya existiera, pisarlo reemplazaría el
+          // contenido de un blob conservando su identidad, que es justo el
+          // ataque que el direccionamiento por contenido tiene que impedir.
+          'x-upsert': 'false',
+        },
+        body: entry.buffer,
+      });
+
+      if (!res.ok) {
+        throw new ShiloError(
+          `No se pudo subir el contenido de "${entry.path}": HTTP ${res.status}`,
+          { status: res.status }
+        );
+      }
+      uploaded = true;
+    }
+
+    return { url, payload, uploaded, credentials: begun.credentials };
+  }
+
+  /**
+   * Crea una carpeta bajo `parentPath` (vacío = raíz). Un 409 significa que ya
+   * existe: no es fatal, devolvemos `{ folder, existed: true }`.
+   * `{ folder, existed: <bool>, credentials }`.
+   */
+  async createFolder(projectId, folderName, parentPath = '', credentials) {
+    const url = this._fileUrl(projectId, parentPath);
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { name: folderName, type: 'folder' },
+    });
+    if (res.status === 409) {
+      const existing = (data && (data.folder || data.file)) || { name: folderName };
+      return { folder: existing, existed: true, credentials: creds };
+    }
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo crear la carpeta "${folderName}": ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const folder = (data && (data.file || data)) || null;
+    return { folder, existed: false, credentials: creds };
+  }
+
+  /**
+   * Asegura que existan todas las carpetas del path de un archivo.
+   * Estrategia anti-duplicados: Shilo puede no devolver 409 fiable, así que
+   * listamos el padre antes de crear y reutilizamos la carpeta si ya existe.
+   * `ensuredCache` (Set de rutas completas) evita re-listar dentro de una corrida.
+   * Devuelve las credenciales (posiblemente refrescadas).
+   */
+  async ensurePath(projectId, filePath, credentials, ensuredCache = null) {
+    const parts = filePath.split('/').filter(Boolean);
+    parts.pop(); // quitar el nombre del archivo
+    if (parts.length === 0) return credentials;
+
+    let currentCreds = credentials;
+    let parentPath = '';
+
+    for (const folderName of parts) {
+      const fullPath = parentPath ? `${parentPath}/${folderName}` : folderName;
+
+      if (ensuredCache && ensuredCache.has(fullPath)) {
+        parentPath = fullPath;
+        continue;
+      }
+
+      let exists = false;
+      try {
+        const listResult = await this.listFiles(projectId, currentCreds, parentPath);
+        currentCreds = listResult.credentials;
+        exists = listResult.files.some((e) => e && e.type === 'folder' && e.name === folderName);
+      } catch (_) {
+        // El padre puede no existir aún: dejamos que createFolder lo cree.
+        exists = false;
+      }
+
+      if (!exists) {
+        const result = await this.createFolder(projectId, folderName, parentPath, currentCreds);
+        currentCreds = result.credentials;
+      }
+
+      if (ensuredCache) ensuredCache.add(fullPath);
+      parentPath = fullPath;
+    }
+
+    return currentCreds;
+  }
+
+  /**
+   * Lista el historial de commits del proyecto (más nuevo primero).
+   * `includeFiles` pide además los `commit_files` de cada commit, que es lo que
+   * permite saber quién tocó cada archivo por última vez.
+   * Devuelve `{ commits, hasMore, credentials }`.
+   */
+  async listCommits(projectId, credentials, { limit = 20, page = 1, includeFiles = false } = {}) {
+    const params = new URLSearchParams({ limit: String(limit), page: String(page) });
+    if (includeFiles) params.set('include', 'files');
+    const url = `${this.baseURL}/api/commits/${projectId}?${params.toString()}`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo listar el historial: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const commits = data && Array.isArray(data.commits) ? data.commits : [];
+    const hasMore = !!(data && data.pagination && data.pagination.hasMore);
+    return { commits, hasMore, credentials: creds };
+  }
+
+  /**
+   * Crea un commit con la lista de cambios de archivos (máx 100 por lote).
+   * `changes`: [{ file_id, action, previous_storage_path?, new_storage_path? }].
+   * Devuelve `{ commit, credentials }`.
+   */
+  async createCommit(projectId, message, changes, credentials, { card } = {}) {
+    const url = `${this.baseURL}/api/commits/${projectId}`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { message, files: changes, ...(card ? { card } : {}) },
+    });
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo crear el commit: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    const commit = (data && data.commit) || data;
+    return { commit, credentials: creds };
+  }
+
+  /**
+   * Revisión humana (Etapa 4). `version` es `actual`, un oid o un prefijo de al
+   * menos 7 caracteres (lo que imprime `shilo log`). El servidor la resuelve y
+   * devuelve el oid completo. Devuelve `{ version, reviews, credentials }`.
+   */
+  async listReviews(projectId, version, credentials) {
+    const params = new URLSearchParams({ reviews: version || 'actual' });
+    const url = `${this.baseURL}/api/commits/${projectId}?${params.toString()}`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudieron leer las revisiones: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    return {
+      version: data && data.version,
+      reviews: data && Array.isArray(data.reviews) ? data.reviews : [],
+      credentials: creds,
+    };
+  }
+
+  /**
+   * Deja constancia de una revisión. `verdict`: aprobado | con_reparos |
+   * rechazado; la nota es obligatoria salvo en `aprobado`.
+   * Devuelve `{ version, review, reviews, credentials }`.
+   */
+  async review(projectId, { version, verdict, note }, credentials) {
+    const url = `${this.baseURL}/api/commits/${projectId}`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { review: { version: version || 'actual', verdict, ...(note ? { note } : {}) } },
+    });
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo registrar la revisión: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    return {
+      version: data && data.version,
+      review: data && data.review,
+      reviews: data && Array.isArray(data.reviews) ? data.reviews : [],
+      credentials: creds,
+    };
+  }
+
+  /**
+   * Propuestas (Etapa 3). Guardar es proponer: el cliente dice de qué versión
+   * partió (`base`, el oid de la versión actual que vio) y qué cambió, y el
+   * servidor decide si lo aplica solo o si lo deja abierto porque alguien más
+   * cambió los mismos archivos. Es lo que hace que un push nunca pise trabajo
+   * ajeno.
+   */
+
+  /**
+   * Lista las propuestas del proyecto y, de paso, la versión actual (`main`).
+   * Devuelve `{ main, proposals, credentials }`. Un servidor sin la Etapa 3
+   * responde 404: se marca `notSupported`.
+   */
+  async listProposals(projectId, credentials, { state = null } = {}) {
+    const params = new URLSearchParams({ projectId });
+    if (state) params.set('state', state);
+    const url = `${this.baseURL}/api/projects/proposals?${params.toString()}`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials);
+    if (!res.ok) {
+      throw new ShiloError(
+        `No se pudo leer la versión actual: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data, notSupported: res.status === 404 || res.status === 405 }
+      );
+    }
+    return {
+      main: (data && data.main) || null,
+      proposals: data && Array.isArray(data.proposals) ? data.proposals : [],
+      credentials: creds,
+    };
+  }
+
+  /**
+   * Abre una propuesta y deja que el servidor intente aplicarla.
+   *
+   * `changes`: [{ path, content, mime_type? } | { path, oid } | { path, delete: true }].
+   *
+   * `agent` declara que esto no lo escribió una persona: `{ name, model,
+   * session_id, tool }`. `prompt` es el texto que se lo pidió, y sube sólo si
+   * quien llama lo pasa — nunca se infiere del entorno, porque un prompt puede
+   * llevar adentro cualquier cosa que se haya pegado en la terminal.
+   *
+   * `card` es la tarjeta del tablero que pidió el cambio. Va además del trailer
+   * `[card: …]` del mensaje, que se queda porque es el formato de todo lo ya
+   * guardado; la clave es la que se puede consultar.
+   *
+   * Devuelve `{ applied, empty, proposal, conflicts, blockedBy, main, message,
+   * warnings, credentials }`. Los 200 y 202 son respuestas normales (aplicada /
+   * quedó abierta); cualquier otro estado es error.
+   */
+  async propose(projectId, { base, title, summary, changes, agent, prompt, card }, credentials) {
+    const url = `${this.baseURL}/api/projects/proposals`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: {
+        projectId,
+        base,
+        title,
+        summary,
+        changes,
+        ...(agent ? { agent } : {}),
+        ...(prompt ? { prompt } : {}),
+        ...(card ? { card } : {}),
+      },
+    });
+    if (!res.ok && res.status !== 202) {
+      throw new ShiloError(
+        `No se pudo proponer el cambio: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data, notSupported: res.status === 404 || res.status === 405 }
+      );
+    }
+    return {
+      applied: !!(data && data.applied),
+      empty: !!(data && data.empty),
+      proposal: (data && data.proposal) || null,
+      conflicts: data && Array.isArray(data.conflicts) ? data.conflicts : [],
+      blockedBy: data && Array.isArray(data.blocked_by) ? data.blocked_by : [],
+      main: (data && data.main) || null,
+      message: (data && data.message) || '',
+      warnings: data && Array.isArray(data.warnings) ? data.warnings : [],
+      credentials: creds,
+    };
+  }
+
+  /**
+   * Resuelve una propuesta abierta: `apply` (dueño) o `discard` (dueño o
+   * autor). Devuelve `{ applied, proposal, conflicts, main, credentials }`; con
+   * `apply` un 409 significa que sigue en conflicto y viene con los datos.
+   */
+  async resolveProposal(projectId, id, action, credentials) {
+    const url = `${this.baseURL}/api/projects/proposals`;
+    const { res, data, credentials: creds } = await this._authFetch(url, credentials, {
+      method: 'POST',
+      body: { projectId, id, action },
+    });
+    const stillOpen = action === 'apply' && res.status === 409 && data && data.proposal;
+    if (!res.ok && !stillOpen) {
+      throw new ShiloError(
+        `No se pudo resolver la propuesta: ${this._errMessage(data, `HTTP ${res.status}`)}`,
+        { status: res.status, body: data }
+      );
+    }
+    return {
+      applied: !!(data && data.applied),
+      proposal: (data && data.proposal) || null,
+      conflicts: data && Array.isArray(data.conflicts) ? data.conflicts : [],
+      main: (data && data.main) || null,
+      message: (data && data.message) || '',
+      credentials: creds,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Lectura del grafo por oid (Etapa 5, B1) — lo que baja `shilo export`.
+  // -------------------------------------------------------------------------
+
+  /**
+   * GET de lectura del grafo. Sin `credentials` va sin sesión: un proyecto
+   * público se exporta sin cuenta, igual que se mira sin cuenta.
+   */
+  async _graphGet(projectId, params, credentials) {
+    const query = new URLSearchParams({ projectId, ...params });
+    const url = `${this.baseURL}/api/projects/graph?${query.toString()}`;
+    if (credentials) return this._authFetch(url, credentials);
+    const { res, data } = await this._fetch(url, { method: 'GET' });
+    return { res, data, credentials: null };
+  }
+
+  _graphError(que, res, data) {
+    return new ShiloError(`No se pudo leer ${que}: ${this._errMessage(data, `HTTP ${res.status}`)}`, {
+      status: res.status,
+      body: data,
+    });
+  }
+
+  /**
+   * La historia alcanzable desde `refs` (por defecto `main`), menos lo
+   * alcanzable desde `desde`, padres primero. Pide todas las páginas y fija
+   * las cabezas de la primera en las siguientes, así un guardado ajeno en el
+   * medio no mezcla dos historias. Devuelve
+   * `{ refs, heads, commits, identities, credentials }`.
+   *
+   * `identities` junta las identidades congeladas de los autores de cada
+   * página (B2, migración 018). Si alguna página vino sin ellas —el servidor
+   * no tiene la 018 o falló al congelar— es `null`: una firma a medias daría
+   * SHA-1 que no se repiten, así que el que exporta tiene que cortar.
+   */
+  async graphHistory(projectId, credentials, { refs = ['main'], desde = [], limit = 1000 } = {}) {
+    const base = { objects: 'history', limit: String(limit) };
+    if (desde.length > 0) base.desde = desde.join(',');
+
+    let creds = credentials;
+    let primera = null;
+    const commits = [];
+    let identities = {};
+    let offset = 0;
+
+    while (offset !== null) {
+      const params = primera
+        ? { ...base, heads: primera.heads.join(','), offset: String(offset) }
+        : { ...base, refs: refs.join(',') };
+      // eslint-disable-next-line no-await-in-loop
+      const { res, data, credentials: c } = await this._graphGet(projectId, params, creds);
+      if (!res.ok) throw this._graphError('la historia', res, data);
+      creds = c || creds;
+      if (!primera) primera = data;
+      commits.push(...(data.commits || []));
+      identities = identities && data.identities ? { ...identities, ...data.identities } : null;
+      // Una historia vacía no tiene cabezas que fijar: no hay segunda página.
+      offset = primera.heads.length > 0 ? data.next_offset : null;
+    }
+
+    return { refs: primera.refs || {}, heads: primera.heads, commits, identities, credentials: creds };
+  }
+
+  /**
+   * Árboles por oid, ya verificados contra su oid y parseados. Parte los
+   * pedidos de a 100 y vuelve a pedir los `pendientes` que el servidor dejó
+   * afuera por tamaño. Devuelve `{ trees: {oid: entradas}, faltan, credentials }`.
+   */
+  async graphTrees(projectId, oids, credentials) {
+    const trees = {};
+    const faltan = [];
+    let creds = credentials;
+    let cola = [...new Set(oids)];
+
+    while (cola.length > 0) {
+      const tanda = cola.slice(0, 100);
+      cola = cola.slice(100);
+      // eslint-disable-next-line no-await-in-loop
+      const { res, data, credentials: c } = await this._graphGet(
+        projectId, { objects: 'trees', oids: tanda.join(',') }, creds
+      );
+      if (!res.ok) throw this._graphError('los árboles', res, data);
+      creds = c || creds;
+
+      for (const [oid, texto] of Object.entries(data.trees || {})) trees[oid] = leerArbolShilo(oid, texto);
+      faltan.push(...(data.faltan || []));
+      const pendientes = data.pendientes || [];
+      // Si ni uno entró, el servidor no está avanzando: cortar antes que girar.
+      if (pendientes.length === tanda.length) throw this._graphError('los árboles', res, { error: 'sin avance' });
+      cola = [...pendientes, ...cola];
+    }
+
+    return { trees, faltan, credentials: creds };
+  }
+
+  /**
+   * URLs firmadas de blobs por oid, de a 100. No baja nada: los bytes se bajan
+   * con `downloadBinary`, y el sha256 se verifica al convertir. Devuelve
+   * `{ blobs: {oid: {size, url}}, faltan, credentials }`; el blob vacío viene
+   * con `url: null`.
+   */
+  async graphBlobs(projectId, oids, credentials) {
+    const blobs = {};
+    const faltan = [];
+    let creds = credentials;
+    const lista = [...new Set(oids)];
+
+    for (let i = 0; i < lista.length; i += 100) {
+      // eslint-disable-next-line no-await-in-loop
+      const { res, data, credentials: c } = await this._graphGet(
+        projectId, { objects: 'blobs', oids: lista.slice(i, i + 100).join(',') }, creds
+      );
+      if (!res.ok) throw this._graphError('los archivos', res, data);
+      creds = c || creds;
+      Object.assign(blobs, data.blobs || {});
+      faltan.push(...(data.faltan || []));
+    }
+
+    return { blobs, faltan, credentials: creds };
+  }
+}
+
+module.exports = { ShiloClient, ShiloError };