@kjerneverk/riotplan-cloud 1.0.0-dev.0

package/dist/index.js

@@ -0,0 +1,1113 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, rename, mkdir, stat, rm, readdir } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+const SYNC_MANIFEST_VERSION = 1;
+const SYNC_MANIFEST_FILE = ".riotplan-sync-manifest.json";
+const REMOTE_INDEX_SCHEMA_VERSION = 1;
+const REMOTE_INDEX_FILE = ".riotplan-sync-index-v1.json";
+const REMOTE_INDEX_CACHE_FILE = ".riotplan-remote-index-cache-v1.json";
+const REMOTE_INDEX_DOWNLOAD_TMP = ".riotplan-remote-index-download.tmp.json";
+function buildSyncDiff(remoteObjects, manifestObjects, localFiles) {
+  const added = [];
+  const changed = [];
+  const unchanged = [];
+  const remotePaths = new Set(Object.keys(remoteObjects));
+  for (const relativePath of remotePaths) {
+    const remote = remoteObjects[relativePath];
+    const localExists = localFiles.has(relativePath);
+    const manifest = manifestObjects?.[relativePath];
+    if (!localExists) {
+      added.push(relativePath);
+      continue;
+    }
+    if (!manifest) {
+      changed.push(relativePath);
+      continue;
+    }
+    const byGeneration = manifest.generation && remote.generation && manifest.generation === remote.generation;
+    const byEtag = manifest.etag && remote.etag && manifest.etag === remote.etag;
+    const byMd5 = manifest.md5Hash && remote.md5Hash && manifest.md5Hash === remote.md5Hash;
+    if (byGeneration || byEtag || byMd5) {
+      unchanged.push(relativePath);
+    } else {
+      changed.push(relativePath);
+    }
+  }
+  const deletedLocal = [];
+  for (const localRelative of localFiles) {
+    if (!remotePaths.has(localRelative)) {
+      deletedLocal.push(localRelative);
+    }
+  }
+  return { added, changed, unchanged, deletedLocal };
+}
+function isRetryableError(error) {
+  if (!error || typeof error !== "object") return false;
+  const code = error.code;
+  const message = String(error.message || "").toLowerCase();
+  if (typeof code === "number" && [408, 429, 500, 502, 503, 504].includes(code)) return true;
+  if (typeof code === "string" && ["ETIMEDOUT", "ECONNRESET", "EAI_AGAIN"].includes(code)) return true;
+  return message.includes("timeout") || message.includes("temporar") || message.includes("rate");
+}
+async function withRetry(fn, retries = 2) {
+  let attempt = 0;
+  let lastError;
+  while (attempt <= retries) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retries || !isRetryableError(error)) {
+        throw error;
+      }
+      const backoffMs = 100 * Math.pow(2, attempt);
+      await new Promise((resolve2) => setTimeout(resolve2, backoffMs));
+    }
+    attempt += 1;
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+function normalizePrefix(prefix) {
+  if (!prefix) {
+    return "";
+  }
+  return prefix.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function toObjectName(prefix, relativePath) {
+  const normalizedRelative = relativePath.split("\\").join("/");
+  return prefix ? `${prefix}/${normalizedRelative}` : normalizedRelative;
+}
+function toRelativePath(prefix, objectName) {
+  if (!prefix) {
+    return objectName;
+  }
+  if (objectName.startsWith(`${prefix}/`)) {
+    return objectName.slice(prefix.length + 1);
+  }
+  return objectName;
+}
+function isInternalSyncControlFile(relativePath) {
+  const normalized = relativePath.split("\\").join("/");
+  const base = normalized.split("/").pop() || normalized;
+  return base === SYNC_MANIFEST_FILE || base === REMOTE_INDEX_FILE || base === REMOTE_INDEX_CACHE_FILE || base === REMOTE_INDEX_DOWNLOAD_TMP;
+}
+async function loadRemoteSyncIndexCache(localDirectory) {
+  const cachePath = join(localDirectory, REMOTE_INDEX_CACHE_FILE);
+  try {
+    const raw = await readFile(cachePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || parsed.version !== REMOTE_INDEX_SCHEMA_VERSION || typeof parsed.indexObject !== "string" || !parsed.objects || typeof parsed.objects !== "object") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function saveRemoteSyncIndexCache(localDirectory, cache) {
+  const path = join(localDirectory, REMOTE_INDEX_CACHE_FILE);
+  const tempPath = `${path}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(cache, null, 2)}
+`, "utf8");
+  await rename(tempPath, path);
+}
+function metadataStringValue(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function metadataNumberValue(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return void 0;
+}
+function parseRemoteMetadata(metadata) {
+  return {
+    md5Hash: metadataStringValue(metadata?.md5Hash),
+    generation: metadataStringValue(metadata?.generation),
+    etag: metadataStringValue(metadata?.etag),
+    size: metadataNumberValue(metadata?.size),
+    updatedAt: metadataStringValue(metadata?.updated)
+  };
+}
+function normalizeRemoteIndexObjects(objects) {
+  if (!objects || typeof objects !== "object") {
+    return {};
+  }
+  const normalized = {};
+  for (const [rawPath, rawState] of Object.entries(objects)) {
+    const path = typeof rawPath === "string" ? rawPath : "";
+    if (!path || isInternalSyncControlFile(path)) {
+      continue;
+    }
+    const state = rawState;
+    normalized[path] = {
+      path,
+      generation: metadataStringValue(state?.generation),
+      etag: metadataStringValue(state?.etag),
+      md5Hash: metadataStringValue(state?.md5Hash),
+      size: metadataNumberValue(state?.size),
+      updatedAt: metadataStringValue(state?.updatedAt)
+    };
+  }
+  return normalized;
+}
+async function collectLocalFiles(rootDir) {
+  const entries = await readdir(rootDir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await collectLocalFiles(fullPath);
+      for (const child of nested) {
+        files.push(join(entry.name, child));
+      }
+      continue;
+    }
+    files.push(entry.name);
+  }
+  return files;
+}
+async function fileMd5Base64(path) {
+  const buffer = await readFile(path);
+  return createHash("md5").update(buffer).digest("base64");
+}
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveRemoteMd5(file) {
+  if (file.metadata?.md5Hash) {
+    return file.metadata.md5Hash;
+  }
+  if (typeof file.getMetadata === "function") {
+    try {
+      const [metadata] = await file.getMetadata();
+      const md5Hash = typeof metadata?.md5Hash === "string" ? metadata.md5Hash : void 0;
+      if (md5Hash) {
+        file.metadata = { ...file.metadata || {}, md5Hash };
+      }
+      return md5Hash;
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+async function resolveRemoteMetadata(file) {
+  const fromInline = parseRemoteMetadata(file.metadata);
+  if (fromInline.md5Hash || fromInline.generation || fromInline.etag || fromInline.size !== void 0 || fromInline.updatedAt) {
+    return fromInline;
+  }
+  if (typeof file.getMetadata !== "function") {
+    return fromInline;
+  }
+  try {
+    const [metadata] = await file.getMetadata();
+    const parsed = parseRemoteMetadata(metadata);
+    const md5Hash = parsed.md5Hash || file.metadata?.md5Hash;
+    const generation = parsed.generation;
+    const etag = parsed.etag;
+    const size = parsed.size;
+    const updatedAt = parsed.updatedAt;
+    if (md5Hash) {
+      file.metadata = { ...file.metadata || {}, md5Hash };
+    }
+    return { md5Hash, generation, etag, size, updatedAt };
+  } catch {
+    return {
+      md5Hash: file.metadata?.md5Hash
+    };
+  }
+}
+async function loadRemoteSyncIndex(bucket, prefix, localDirectory, onDebugEvent) {
+  const indexObject = toObjectName(prefix, REMOTE_INDEX_FILE);
+  const remoteIndexFile = bucket.file(indexObject);
+  if (!remoteIndexFile || typeof remoteIndexFile.getMetadata !== "function") {
+    return { objects: null, usedCachedIndex: false };
+  }
+  let metadata;
+  try {
+    const [resolved] = await withRetry(() => remoteIndexFile.getMetadata());
+    metadata = resolved;
+  } catch (error) {
+    if (error?.code === 404) {
+      return { objects: null, usedCachedIndex: false };
+    }
+    onDebugEvent?.("sync_down.index.metadata_failed", {
+      indexObject,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return { objects: null, usedCachedIndex: false };
+  }
+  const indexEtag = metadataStringValue(metadata?.etag);
+  const indexGeneration = metadataStringValue(metadata?.generation);
+  const cache = await loadRemoteSyncIndexCache(localDirectory);
+  if (cache && cache.indexObject === indexObject && (indexEtag && cache.etag === indexEtag || indexGeneration && cache.generation === indexGeneration)) {
+    onDebugEvent?.("sync_down.index.cache_hit", {
+      indexObject,
+      objectCount: Object.keys(cache.objects || {}).length
+    });
+    return {
+      objects: normalizeRemoteIndexObjects(cache.objects),
+      indexEtag,
+      indexGeneration,
+      usedCachedIndex: true
+    };
+  }
+  const downloadPath = join(localDirectory, REMOTE_INDEX_DOWNLOAD_TMP);
+  try {
+    await withRetry(() => remoteIndexFile.download({ destination: downloadPath }));
+    const raw = await readFile(downloadPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== REMOTE_INDEX_SCHEMA_VERSION || !parsed.objects || typeof parsed.objects !== "object") {
+      onDebugEvent?.("sync_down.index.invalid_schema", {
+        indexObject,
+        version: parsed.version ?? null
+      });
+      return { objects: null, indexEtag, indexGeneration, usedCachedIndex: false };
+    }
+    const normalizedObjects = normalizeRemoteIndexObjects(parsed.objects);
+    await saveRemoteSyncIndexCache(localDirectory, {
+      version: REMOTE_INDEX_SCHEMA_VERSION,
+      indexObject,
+      etag: indexEtag,
+      generation: indexGeneration,
+      updatedAt: metadataStringValue(metadata?.updated),
+      objects: normalizedObjects
+    });
+    onDebugEvent?.("sync_down.index.downloaded", {
+      indexObject,
+      objectCount: Object.keys(normalizedObjects).length
+    });
+    return {
+      objects: normalizedObjects,
+      indexEtag,
+      indexGeneration,
+      usedCachedIndex: false
+    };
+  } catch (error) {
+    onDebugEvent?.("sync_down.index.download_failed", {
+      indexObject,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return { objects: null, indexEtag, indexGeneration, usedCachedIndex: false };
+  } finally {
+    await rm(downloadPath, { force: true }).catch(() => void 0);
+  }
+}
+async function writeRemoteSyncIndex(bucket, prefix, localDirectory, objects, onDebugEvent) {
+  const indexObject = toObjectName(prefix, REMOTE_INDEX_FILE);
+  const tempPath = join(localDirectory, `${REMOTE_INDEX_FILE}.tmp`);
+  const payload = {
+    version: REMOTE_INDEX_SCHEMA_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    objects
+  };
+  try {
+    await writeFile(tempPath, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+    await withRetry(() => bucket.upload(tempPath, { destination: indexObject }));
+    onDebugEvent?.("sync_up.index.written", {
+      indexObject,
+      objectCount: Object.keys(objects).length
+    });
+  } finally {
+    await rm(tempPath, { force: true }).catch(() => void 0);
+  }
+}
+async function loadSyncManifest(localDirectory) {
+  const manifestPath = join(localDirectory, SYNC_MANIFEST_FILE);
+  try {
+    const raw = await readFile(manifestPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || parsed.version !== SYNC_MANIFEST_VERSION || !parsed.objects) {
+      return { manifest: null, invalidated: true };
+    }
+    return { manifest: parsed, invalidated: false };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { manifest: null, invalidated: false };
+    }
+    return { manifest: null, invalidated: true };
+  }
+}
+async function writeSyncManifest(localDirectory, objects) {
+  const manifestPath = join(localDirectory, SYNC_MANIFEST_FILE);
+  const tempManifestPath = `${manifestPath}.tmp`;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const payload = {
+    version: SYNC_MANIFEST_VERSION,
+    createdAt: now,
+    updatedAt: now,
+    objects
+  };
+  await writeFile(tempManifestPath, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  await rename(tempManifestPath, manifestPath);
+}
+async function createStorageClient(auth) {
+  let credentials;
+  if (auth.credentialsJson) {
+    try {
+      credentials = JSON.parse(auth.credentialsJson);
+    } catch (error) {
+      throw new Error(`Invalid cloud.credentialsJson JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const moduleName = "@google-cloud/storage";
+  const storageModule = await import(moduleName);
+  return new storageModule.Storage({
+    projectId: auth.projectId,
+    keyFilename: auth.keyFilename,
+    credentials
+  });
+}
+class GcsMirror {
+  auth;
+  bucketName;
+  prefix;
+  localDirectory;
+  includeFile;
+  incrementalSyncEnabled;
+  onDebugEvent;
+  constructor(options) {
+    this.auth = options.auth;
+    this.bucketName = options.location.bucket;
+    this.prefix = normalizePrefix(options.location.prefix);
+    this.localDirectory = resolve(options.localDirectory);
+    this.includeFile = options.includeFile || (() => true);
+    this.incrementalSyncEnabled = options.incrementalSyncEnabled !== false;
+    this.onDebugEvent = options.onDebugEvent;
+  }
+  async syncDown() {
+    const startedAt = Date.now();
+    this.onDebugEvent?.("sync_down.start", {
+      bucket: this.bucketName,
+      prefix: this.prefix,
+      localDirectory: this.localDirectory
+    });
+    const mkdirStartedAt = Date.now();
+    await mkdir(this.localDirectory, { recursive: true });
+    const mkdirMs = Date.now() - mkdirStartedAt;
+    this.onDebugEvent?.("sync_down.phase.mkdir", { elapsedMs: mkdirMs });
+    const clientStartedAt = Date.now();
+    const storage = await createStorageClient(this.auth);
+    const createClientMs = Date.now() - clientStartedAt;
+    this.onDebugEvent?.("sync_down.phase.create_client", { elapsedMs: createClientMs });
+    const bucket = storage.bucket(this.bucketName);
+    const listRemoteStartedAt = Date.now();
+    const remoteIndex = await loadRemoteSyncIndex(bucket, this.prefix, this.localDirectory, this.onDebugEvent);
+    let files = [];
+    let usedRemoteIndex = false;
+    if (remoteIndex.objects) {
+      usedRemoteIndex = true;
+    } else {
+      [files] = await withRetry(() => bucket.getFiles({ prefix: this.prefix || void 0 }));
+    }
+    const listRemoteMs = Date.now() - listRemoteStartedAt;
+    this.onDebugEvent?.("sync_down.phase.list_remote", {
+      elapsedMs: listRemoteMs,
+      listedCount: usedRemoteIndex ? Object.keys(remoteIndex.objects || {}).length : files.length,
+      source: usedRemoteIndex ? "gcs-index" : "bucket-list",
+      usedCachedIndex: remoteIndex.usedCachedIndex
+    });
+    const { manifest, invalidated } = this.incrementalSyncEnabled ? await loadSyncManifest(this.localDirectory) : { manifest: null, invalidated: false };
+    if (invalidated) {
+      this.onDebugEvent?.("sync_down.manifest.invalidated", {
+        localDirectory: this.localDirectory,
+        reason: "unsupported_or_corrupt_manifest"
+      });
+    }
+    const localFilesAtStart = await collectLocalFiles(this.localDirectory);
+    const localTrackedAtStart = new Set(
+      localFilesAtStart.filter((relativePath) => this.includeFile(relativePath))
+    );
+    const remoteStateByPath = {};
+    const remoteFileByPath = /* @__PURE__ */ new Map();
+    if (usedRemoteIndex && remoteIndex.objects) {
+      for (const [relativePath, objectState] of Object.entries(remoteIndex.objects)) {
+        if (!relativePath || isInternalSyncControlFile(relativePath) || !this.includeFile(relativePath)) {
+          continue;
+        }
+        remoteStateByPath[relativePath] = objectState;
+        remoteFileByPath.set(relativePath, bucket.file(toObjectName(this.prefix, relativePath)));
+      }
+    } else {
+      for (const file of files) {
+        const objectName = file.name;
+        if (objectName.endsWith("/")) {
+          continue;
+        }
+        const relativePath = toRelativePath(this.prefix, objectName);
+        if (!relativePath || isInternalSyncControlFile(relativePath) || !this.includeFile(relativePath)) {
+          continue;
+        }
+        remoteFileByPath.set(relativePath, file);
+        const remoteMeta = await resolveRemoteMetadata(file);
+        remoteStateByPath[relativePath] = {
+          path: relativePath,
+          generation: remoteMeta.generation,
+          etag: remoteMeta.etag,
+          md5Hash: remoteMeta.md5Hash,
+          size: remoteMeta.size,
+          updatedAt: remoteMeta.updatedAt
+        };
+      }
+    }
+    const remoteSet = new Set(Object.keys(remoteStateByPath));
+    const remoteIncludedCount = remoteSet.size;
+    let diff;
+    if (!this.incrementalSyncEnabled) {
+      diff = {
+        added: [...remoteSet],
+        changed: [],
+        unchanged: [],
+        deletedLocal: [...localTrackedAtStart].filter((path) => !remoteSet.has(path))
+      };
+    } else {
+      try {
+        diff = buildSyncDiff(remoteStateByPath, manifest?.objects, localTrackedAtStart);
+      } catch (error) {
+        this.onDebugEvent?.("sync_down.diff_recovery", {
+          reason: error instanceof Error ? error.message : String(error),
+          strategy: "full_resync"
+        });
+        diff = {
+          added: [],
+          changed: [...remoteSet],
+          unchanged: [],
+          deletedLocal: [...localTrackedAtStart].filter((path) => !remoteSet.has(path))
+        };
+      }
+    }
+    let changedCount = diff.added.length + diff.changed.length;
+    let skippedUnchangedCount = diff.unchanged.length;
+    let downloadedCount = 0;
+    let downloadedBytes = 0;
+    const manifestObjects = {};
+    const downloadStartedAt = Date.now();
+    const downloadTargets = [...diff.added, ...diff.changed];
+    for (const relativePath of downloadTargets) {
+      const file = remoteFileByPath.get(relativePath);
+      if (!file) {
+        continue;
+      }
+      const localPath = join(this.localDirectory, relativePath);
+      let shouldDownload = true;
+      const remoteMeta = remoteStateByPath[relativePath];
+      const existingManifestEntry = manifest?.objects?.[relativePath];
+      const existsLocally = await fileExists(localPath);
+      if (this.incrementalSyncEnabled && existsLocally && existingManifestEntry) {
+        const unchangedByManifest = existingManifestEntry.generation && remoteMeta?.generation && existingManifestEntry.generation === remoteMeta.generation;
+        if (unchangedByManifest) {
+          shouldDownload = false;
+        }
+      }
+      if (this.incrementalSyncEnabled && existsLocally && shouldDownload) {
+        const remoteMd5 = remoteMeta?.md5Hash || await resolveRemoteMd5(file);
+        if (remoteMd5) {
+          const localMd5 = await fileMd5Base64(localPath);
+          shouldDownload = localMd5 !== remoteMd5;
+        }
+      }
+      if (!shouldDownload) {
+        skippedUnchangedCount += 1;
+        changedCount -= 1;
+        continue;
+      }
+      await mkdir(dirname(localPath), { recursive: true });
+      const downloadFileStartedAt = Date.now();
+      await withRetry(() => file.download({ destination: localPath }));
+      const fileElapsedMs = Date.now() - downloadFileStartedAt;
+      downloadedCount += 1;
+      try {
+        downloadedBytes += (await stat(localPath)).size;
+      } catch {
+      }
+      if (fileElapsedMs >= 250) {
+        this.onDebugEvent?.("sync_down.file_download", {
+          path: relativePath,
+          elapsedMs: fileElapsedMs
+        });
+      }
+      manifestObjects[relativePath] = {
+        path: relativePath,
+        generation: remoteMeta?.generation,
+        etag: remoteMeta?.etag,
+        md5Hash: remoteMeta?.md5Hash,
+        size: remoteMeta?.size,
+        updatedAt: remoteMeta?.updatedAt,
+        localPath: relativePath,
+        lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    for (const relativePath of remoteSet) {
+      if (!manifestObjects[relativePath] && manifest?.objects?.[relativePath]) {
+        manifestObjects[relativePath] = {
+          ...manifest.objects[relativePath],
+          lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+    }
+    const downloadMs = Date.now() - downloadStartedAt;
+    this.onDebugEvent?.("sync_down.phase.download", {
+      elapsedMs: downloadMs,
+      downloadedCount,
+      includedCount: remoteIncludedCount,
+      changedCount,
+      skippedUnchangedCount,
+      downloadedBytes
+    });
+    const listLocalStartedAt = Date.now();
+    const localFiles = await collectLocalFiles(this.localDirectory);
+    const listLocalMs = Date.now() - listLocalStartedAt;
+    this.onDebugEvent?.("sync_down.phase.list_local", { elapsedMs: listLocalMs, scannedCount: localFiles.length });
+    const cleanupStartedAt = Date.now();
+    let removedCount = 0;
+    this.onDebugEvent?.("sync_down.gc.start", {
+      localDirectory: this.localDirectory,
+      deletedLocalCandidates: diff.deletedLocal.length
+    });
+    for (const localRelative of diff.deletedLocal) {
+      if (!remoteSet.has(localRelative)) {
+        await rm(join(this.localDirectory, localRelative), { force: true });
+        removedCount += 1;
+        this.onDebugEvent?.("sync_down.gc.remove_local", {
+          path: localRelative
+        });
+      }
+    }
+    const cleanupMs = Date.now() - cleanupStartedAt;
+    this.onDebugEvent?.("sync_down.gc.complete", {
+      removedCount,
+      elapsedMs: cleanupMs
+    });
+    if (this.incrementalSyncEnabled) {
+      const manifestWriteStartedAt = Date.now();
+      await writeSyncManifest(this.localDirectory, manifestObjects);
+      this.onDebugEvent?.("sync_down.manifest.write_complete", {
+        objectCount: Object.keys(manifestObjects).length,
+        elapsedMs: Date.now() - manifestWriteStartedAt
+      });
+    }
+    const elapsedMs = Date.now() - startedAt;
+    const stats = {
+      bucket: this.bucketName,
+      prefix: this.prefix,
+      localDirectory: this.localDirectory,
+      remoteListedCount: usedRemoteIndex ? remoteIncludedCount : files.length,
+      remoteIncludedCount,
+      changedCount,
+      skippedUnchangedCount,
+      downloadedCount,
+      downloadedBytes,
+      localScannedCount: localFiles.length,
+      removedCount,
+      elapsedMs,
+      phases: {
+        mkdirMs,
+        createClientMs,
+        listRemoteMs,
+        downloadMs,
+        listLocalMs,
+        cleanupMs
+      }
+    };
+    this.onDebugEvent?.("sync_down.complete", stats);
+    return stats;
+  }
+  async syncUp() {
+    const startedAt = Date.now();
+    this.onDebugEvent?.("sync_up.start", {
+      bucket: this.bucketName,
+      prefix: this.prefix,
+      localDirectory: this.localDirectory
+    });
+    const mkdirStartedAt = Date.now();
+    await mkdir(this.localDirectory, { recursive: true });
+    const mkdirMs = Date.now() - mkdirStartedAt;
+    const clientStartedAt = Date.now();
+    const storage = await createStorageClient(this.auth);
+    const createClientMs = Date.now() - clientStartedAt;
+    const bucket = storage.bucket(this.bucketName);
+    const listRemoteStartedAt = Date.now();
+    const [remoteFiles] = await withRetry(() => bucket.getFiles({ prefix: this.prefix || void 0 }));
+    const listRemoteMs = Date.now() - listRemoteStartedAt;
+    const remoteByRelative = /* @__PURE__ */ new Map();
+    for (const remote of remoteFiles) {
+      if (remote.name.endsWith("/")) {
+        continue;
+      }
+      const relativePath = toRelativePath(this.prefix, remote.name);
+      if (!relativePath || isInternalSyncControlFile(relativePath) || !this.includeFile(relativePath)) {
+        continue;
+      }
+      remoteByRelative.set(relativePath, remote);
+    }
+    const listLocalStartedAt = Date.now();
+    const localFiles = await collectLocalFiles(this.localDirectory);
+    const listLocalMs = Date.now() - listLocalStartedAt;
+    const localSet = /* @__PURE__ */ new Set();
+    let localIncludedCount = 0;
+    let uploadedCount = 0;
+    const uploadStartedAt = Date.now();
+    for (const localRelative of localFiles) {
+      if (isInternalSyncControlFile(localRelative) || !this.includeFile(localRelative)) {
+        continue;
+      }
+      localIncludedCount += 1;
+      localSet.add(localRelative);
+      const localPath = join(this.localDirectory, localRelative);
+      const remoteFile = remoteByRelative.get(localRelative);
+      let shouldUpload = true;
+      if (remoteFile) {
+        const remoteMd5 = await resolveRemoteMd5(remoteFile);
+        if (remoteMd5) {
+          const localMd5 = await fileMd5Base64(localPath);
+          shouldUpload = localMd5 !== remoteMd5;
+        }
+      }
+      if (!shouldUpload) {
+        continue;
+      }
+      const objectName = toObjectName(this.prefix, localRelative);
+      const uploadFileStartedAt = Date.now();
+      await withRetry(
+        () => bucket.upload(localPath, {
+          destination: objectName
+        })
+      );
+      const fileElapsedMs = Date.now() - uploadFileStartedAt;
+      uploadedCount += 1;
+      if (fileElapsedMs >= 250) {
+        this.onDebugEvent?.("sync_up.file_upload", {
+          path: localRelative,
+          elapsedMs: fileElapsedMs
+        });
+      }
+    }
+    const uploadMs = Date.now() - uploadStartedAt;
+    let removedRemoteCount = 0;
+    const cleanupStartedAt = Date.now();
+    this.onDebugEvent?.("sync_up.gc.start", {
+      bucket: this.bucketName,
+      prefix: this.prefix,
+      remoteCandidates: remoteFiles.length
+    });
+    for (const remote of remoteFiles) {
+      if (remote.name.endsWith("/")) {
+        continue;
+      }
+      const relativePath = toRelativePath(this.prefix, remote.name);
+      if (!relativePath || isInternalSyncControlFile(relativePath) || !this.includeFile(relativePath)) {
+        continue;
+      }
+      if (!localSet.has(relativePath)) {
+        await withRetry(() => remote.delete({ ignoreNotFound: true }));
+        removedRemoteCount += 1;
+        this.onDebugEvent?.("sync_up.gc.remove_remote", {
+          path: relativePath
+        });
+      }
+    }
+    const cleanupMs = Date.now() - cleanupStartedAt;
+    this.onDebugEvent?.("sync_up.gc.complete", {
+      removedRemoteCount,
+      elapsedMs: cleanupMs
+    });
+    const indexStartedAt = Date.now();
+    const indexObjects = {};
+    for (const localRelative of localSet) {
+      const localPath = join(this.localDirectory, localRelative);
+      const localStats = await stat(localPath).catch(() => null);
+      const md5Hash = await fileMd5Base64(localPath).catch(() => void 0);
+      indexObjects[localRelative] = {
+        path: localRelative,
+        md5Hash,
+        size: localStats?.size,
+        updatedAt: localStats?.mtime ? localStats.mtime.toISOString() : void 0
+      };
+    }
+    await writeRemoteSyncIndex(bucket, this.prefix, this.localDirectory, indexObjects, this.onDebugEvent);
+    this.onDebugEvent?.("sync_up.phase.write_index", {
+      elapsedMs: Date.now() - indexStartedAt,
+      objectCount: Object.keys(indexObjects).length
+    });
+    const elapsedMs = Date.now() - startedAt;
+    const stats = {
+      bucket: this.bucketName,
+      prefix: this.prefix,
+      localDirectory: this.localDirectory,
+      localScannedCount: localFiles.length,
+      localIncludedCount,
+      uploadedCount,
+      remoteListedCount: remoteFiles.length,
+      removedRemoteCount,
+      elapsedMs,
+      phases: {
+        mkdirMs,
+        createClientMs,
+        listLocalMs,
+        uploadMs,
+        listRemoteMs,
+        cleanupMs
+      }
+    };
+    this.onDebugEvent?.("sync_up.complete", stats);
+    return stats;
+  }
+}
+function isTruthy(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return /^(1|true|yes|on)$/i.test(value);
+  }
+  return false;
+}
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+const inFlightOperations = /* @__PURE__ */ new Map();
+const debouncedOperations = /* @__PURE__ */ new Map();
+const lastSuccessfulSyncAtByScope = /* @__PURE__ */ new Map();
+function toInt(value) {
+  if (!value) return void 0;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
+}
+function resolveFreshnessTtlMs(config) {
+  const fromConfig = config?.cloud?.syncFreshnessTtlMs;
+  if (typeof fromConfig === "number" && Number.isFinite(fromConfig) && fromConfig >= 0) {
+    return fromConfig;
+  }
+  return toInt(process.env.RIOTPLAN_CLOUD_SYNC_FRESHNESS_TTL_MS) || 5e3;
+}
+function resolveSyncTimeoutMs(config) {
+  const fromConfig = config?.cloud?.syncTimeoutMs;
+  if (typeof fromConfig === "number" && Number.isFinite(fromConfig) && fromConfig > 0) {
+    return fromConfig;
+  }
+  return toInt(process.env.RIOTPLAN_CLOUD_SYNC_TIMEOUT_MS) || 12e4;
+}
+function resolveSyncUpDebounceMs(_config) {
+  const fromEnv = toInt(process.env.RIOTPLAN_CLOUD_SYNC_UP_DEBOUNCE_MS);
+  if (typeof fromEnv === "number") {
+    return fromEnv;
+  }
+  return 400;
+}
+async function runCoalescedOperation(key, operation, options) {
+  const existing = inFlightOperations.get(key);
+  if (existing) {
+    existing.waiterCount += 1;
+    const result2 = await existing.promise;
+    return {
+      result: result2,
+      coalesced: true,
+      waiterCount: existing.waiterCount
+    };
+  }
+  const timeoutMs = options?.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : 0;
+  const entry = {
+    waiterCount: 0,
+    promise: (async () => {
+      try {
+        if (!timeoutMs) {
+          return await operation();
+        }
+        return await Promise.race([
+          operation(),
+          new Promise((_, reject) => {
+            setTimeout(() => {
+              reject(new Error(`Coalesced operation timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+          })
+        ]);
+      } finally {
+        inFlightOperations.delete(key);
+      }
+    })()
+  };
+  inFlightOperations.set(key, entry);
+  const result = await entry.promise;
+  return {
+    result,
+    coalesced: false,
+    waiterCount: entry.waiterCount
+  };
+}
+async function runDebouncedCoalescedOperation(key, operation, options) {
+  const existing = debouncedOperations.get(key);
+  if (existing) {
+    existing.waiterCount += 1;
+    const result = await existing.promise;
+    return {
+      result,
+      coalesced: true,
+      waiterCount: existing.waiterCount
+    };
+  }
+  const debounceMs = options?.debounceMs && options.debounceMs > 0 ? options.debounceMs : 0;
+  const timeoutMs = options?.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : 0;
+  let timer;
+  const promise = new Promise((resolve2, reject) => {
+    const execute = async () => {
+      const run = async () => operation();
+      const task = timeoutMs ? Promise.race([
+        run(),
+        new Promise((_, timeoutReject) => {
+          setTimeout(() => {
+            timeoutReject(new Error(`Debounced operation timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        })
+      ]) : run();
+      try {
+        resolve2(await task);
+      } catch (error) {
+        reject(error);
+      } finally {
+        debouncedOperations.delete(key);
+      }
+    };
+    if (debounceMs > 0) {
+      timer = setTimeout(() => {
+        void execute();
+      }, debounceMs);
+      return;
+    }
+    void execute();
+  });
+  const state = {
+    promise,
+    waiterCount: 0
+  };
+  debouncedOperations.set(key, state);
+  try {
+    const result = await promise;
+    return {
+      result,
+      coalesced: false,
+      waiterCount: state.waiterCount
+    };
+  } catch (error) {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    throw error;
+  }
+}
+async function createCloudRuntime(config, localPlanDirectory, diagnostics) {
+  const cloudConfig = config?.cloud;
+  const incrementalSyncEnabled = cloudConfig?.incrementalSyncEnabled !== false;
+  const freshnessTtlMs = incrementalSyncEnabled ? resolveFreshnessTtlMs(config) : 0;
+  const syncTimeoutMs = resolveSyncTimeoutMs(config);
+  const syncUpDebounceMs = resolveSyncUpDebounceMs();
+  const enabled = isTruthy(cloudConfig?.enabled) || isTruthy(process.env.RIOTPLAN_CLOUD_ENABLED) || isTruthy(process.env.RIOTPLAN_GCS_ENABLED);
+  if (!enabled) {
+    return {
+      enabled: false,
+      workingDirectory: localPlanDirectory,
+      contextDirectory: localPlanDirectory,
+      syncDown: async () => ({
+        plan: null,
+        context: null,
+        syncFreshHit: false,
+        coalescedWaiterCount: 0
+      }),
+      syncUpPlans: async () => null,
+      syncUpContext: async () => null
+    };
+  }
+  const planBucket = firstNonEmpty(
+    cloudConfig?.planBucket,
+    process.env.RIOTPLAN_PLAN_BUCKET,
+    process.env.RIOTPLAN_GCS_PLAN_BUCKET
+  );
+  const contextBucket = firstNonEmpty(
+    cloudConfig?.contextBucket,
+    process.env.RIOTPLAN_CONTEXT_BUCKET,
+    process.env.RIOTPLAN_GCS_CONTEXT_BUCKET
+  );
+  if (!planBucket || !contextBucket) {
+    throw new Error(
+      "Cloud mode enabled but missing bucket config. Set cloud.planBucket + cloud.contextBucket or RIOTPLAN_PLAN_BUCKET + RIOTPLAN_CONTEXT_BUCKET."
+    );
+  }
+  const cacheRoot = resolve(
+    firstNonEmpty(cloudConfig?.cacheDirectory, process.env.RIOTPLAN_CLOUD_CACHE_DIR) || join(localPlanDirectory, ".cloud-cache")
+  );
+  const planMirrorDir = join(cacheRoot, "plans");
+  const contextMirrorDir = join(cacheRoot, "context");
+  await mkdir(planMirrorDir, { recursive: true });
+  await mkdir(contextMirrorDir, { recursive: true });
+  const auth = {
+    projectId: firstNonEmpty(cloudConfig?.projectId, process.env.GOOGLE_CLOUD_PROJECT),
+    keyFilename: firstNonEmpty(cloudConfig?.keyFilename, process.env.GOOGLE_APPLICATION_CREDENTIALS),
+    credentialsJson: firstNonEmpty(cloudConfig?.credentialsJson, process.env.GOOGLE_CREDENTIALS_JSON)
+  };
+  const planMirror = new GcsMirror({
+    auth,
+    location: {
+      bucket: planBucket,
+      prefix: cloudConfig?.planPrefix
+    },
+    localDirectory: planMirrorDir,
+    includeFile: (relativePath) => relativePath.endsWith(".plan"),
+    incrementalSyncEnabled,
+    onDebugEvent: (event, details) => {
+      diagnostics?.debug?.(`plan.${event}`, details);
+    }
+  });
+  const contextMirror = new GcsMirror({
+    auth,
+    location: {
+      bucket: contextBucket,
+      prefix: cloudConfig?.contextPrefix
+    },
+    localDirectory: contextMirrorDir,
+    incrementalSyncEnabled,
+    onDebugEvent: (event, details) => {
+      diagnostics?.debug?.(`context.${event}`, details);
+    }
+  });
+  return {
+    enabled: true,
+    workingDirectory: planMirrorDir,
+    contextDirectory: contextMirrorDir,
+    syncDown: async (options) => {
+      const startedAt = Date.now();
+      const planScope = `sync_down:${planMirrorDir}:plan`;
+      const contextScope = `sync_down:${contextMirrorDir}:context`;
+      const now = Date.now();
+      const planFresh = freshnessTtlMs > 0 && now - (lastSuccessfulSyncAtByScope.get(planScope) || 0) <= freshnessTtlMs;
+      const contextFresh = freshnessTtlMs > 0 && now - (lastSuccessfulSyncAtByScope.get(contextScope) || 0) <= freshnessTtlMs;
+      if (!options?.forceRefresh && planFresh && contextFresh) {
+        diagnostics?.debug?.("sync_down.fresh_hit", {
+          freshnessTtlMs,
+          planScope,
+          contextScope
+        });
+        return {
+          plan: null,
+          context: null,
+          syncFreshHit: true,
+          coalescedWaiterCount: 0
+        };
+      }
+      diagnostics?.debug?.("sync_down.start", {
+        planBucket,
+        contextBucket,
+        planMirrorDir,
+        contextMirrorDir,
+        incrementalSyncEnabled,
+        freshnessTtlMs,
+        syncTimeoutMs
+      });
+      const [planSync, contextSync] = await Promise.all([
+        runCoalescedOperation(planScope, () => planMirror.syncDown(), { timeoutMs: syncTimeoutMs }),
+        runCoalescedOperation(contextScope, () => contextMirror.syncDown(), { timeoutMs: syncTimeoutMs })
+      ]);
+      const planStats = planSync.result;
+      const contextStats = contextSync.result;
+      lastSuccessfulSyncAtByScope.set(planScope, Date.now());
+      lastSuccessfulSyncAtByScope.set(contextScope, Date.now());
+      const coalescedWaiterCount = planSync.waiterCount + contextSync.waiterCount;
+      const syncFreshHit = planStats.downloadedCount === 0 && contextStats.downloadedCount === 0;
+      diagnostics?.debug?.("sync_down.complete", {
+        elapsedMs: Date.now() - startedAt,
+        syncFreshHit,
+        coalescedWaiterCount,
+        syncOutcome: syncFreshHit ? "fresh-hit" : "full-or-incremental",
+        plan: planStats,
+        context: contextStats
+      });
+      return {
+        plan: planStats,
+        context: contextStats,
+        syncFreshHit,
+        coalescedWaiterCount
+      };
+    },
+    syncUpPlans: async () => {
+      const startedAt = Date.now();
+      diagnostics?.debug?.("sync_up_plans.start", { planBucket, planMirrorDir });
+      const syncUpScope = `sync_up:${planMirrorDir}:plan`;
+      const syncResult = await runDebouncedCoalescedOperation(
+        syncUpScope,
+        () => planMirror.syncUp(),
+        { debounceMs: syncUpDebounceMs, timeoutMs: syncTimeoutMs }
+      );
+      const stats = syncResult.result;
+      if (syncResult.coalesced || syncResult.waiterCount > 0) {
+        diagnostics?.debug?.("sync_up_plans.coalesced", {
+          scope: syncUpScope,
+          coalesced: syncResult.coalesced,
+          coalescedWaiterCount: syncResult.waiterCount,
+          debounceMs: syncUpDebounceMs
+        });
+      }
+      diagnostics?.debug?.("sync_up_plans.complete", {
+        elapsedMs: Date.now() - startedAt,
+        plan: stats,
+        coalesced: syncResult.coalesced,
+        coalescedWaiterCount: syncResult.waiterCount,
+        debounceMs: syncUpDebounceMs
+      });
+      return stats;
+    },
+    syncUpContext: async () => {
+      const startedAt = Date.now();
+      diagnostics?.debug?.("sync_up_context.start", { contextBucket, contextMirrorDir });
+      const syncUpScope = `sync_up:${contextMirrorDir}:context`;
+      const syncResult = await runDebouncedCoalescedOperation(
+        syncUpScope,
+        () => contextMirror.syncUp(),
+        { debounceMs: syncUpDebounceMs, timeoutMs: syncTimeoutMs }
+      );
+      const stats = syncResult.result;
+      if (syncResult.coalesced || syncResult.waiterCount > 0) {
+        diagnostics?.debug?.("sync_up_context.coalesced", {
+          scope: syncUpScope,
+          coalesced: syncResult.coalesced,
+          coalescedWaiterCount: syncResult.waiterCount,
+          debounceMs: syncUpDebounceMs
+        });
+      }
+      diagnostics?.debug?.("sync_up_context.complete", {
+        elapsedMs: Date.now() - startedAt,
+        context: stats,
+        coalesced: syncResult.coalesced,
+        coalescedWaiterCount: syncResult.waiterCount,
+        debounceMs: syncUpDebounceMs
+      });
+      return stats;
+    }
+  };
+}
+export {
+  GcsMirror,
+  buildSyncDiff,
+  createCloudRuntime,
+  loadSyncManifest,
+  runCoalescedOperation,
+  runDebouncedCoalescedOperation,
+  writeSyncManifest
+};
+//# sourceMappingURL=index.js.map