agentel 0.2.0

package/src/sync.js

@@ -0,0 +1,677 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const path = require("path");
+const { fileURLToPath, pathToFileURL } = require("url");
+const { archiveRoot } = require("./archive");
+const { loadConfig, normalizeRemoteEndpointInput, saveConfig } = require("./config");
+const { ensureDir, paths, readJson, writeJson } = require("./paths");
+
+function configureRemoteFromFlags(flags = {}, env = process.env) {
+  const cfg = loadConfig(env);
+  const target = remoteTargetFromFlags(flags, cfg, env, { allowPartial: true });
+  cfg.storage.backend = target.type || cfg.storage.backend || "local";
+  if (flags["device-name"] || flags.deviceName || flags.device || flags["device-slug"] || flags.deviceSlug) {
+    const deviceName = value(flags["device-name"] || flags.deviceName || flags.device || cfg.device?.name || "");
+    cfg.device = {
+      ...(cfg.device || {}),
+      name: deviceName || cfg.device?.name || "",
+      slug: value(flags["device-slug"] || flags.deviceSlug || (deviceName ? slugifyRemoteSegment(deviceName) : cfg.device?.slug || "")) || cfg.device?.slug || ""
+    };
+  }
+  if (flags["sync-mode"] || flags.syncMode || flags.mode) {
+    const mode = normalizeSyncMode(flags["sync-mode"] || flags.syncMode || flags.mode);
+    if (mode !== "upload") throw new Error(`remote sync mode "${mode}" is planned but not implemented yet; use upload mode for now`);
+    cfg.sync = {
+      ...(cfg.sync || {}),
+      mode
+    };
+  }
+  if (flags["sync-interval-minutes"] || flags.syncIntervalMinutes || flags.syncInterval) {
+    cfg.sync = {
+      ...(cfg.sync || {}),
+      intervalMinutes: normalizeSyncInterval(flags["sync-interval-minutes"] || flags.syncIntervalMinutes || flags.syncInterval)
+    };
+  }
+  cfg.remote = {
+    ...(cfg.remote || {}),
+    type: target.type || cfg.remote?.type || cfg.storage.backend,
+    endpoint: target.endpoint || cfg.remote?.endpoint || cfg.remote?.url || "",
+    bucket: target.bucket || cfg.remote?.bucket || "",
+    region: target.region || cfg.remote?.region || "auto",
+    prefix: target.prefix || cfg.remote?.prefix || "agentlog",
+    accessKeyId: target.accessKeyId || cfg.remote?.accessKeyId || "",
+    secretAccessKey: target.secretAccessKey || cfg.remote?.secretAccessKey || ""
+  };
+  if (cfg.remote.endpoint) cfg.remote.url = cfg.remote.endpoint;
+  cfg.updatedAt = new Date().toISOString();
+  saveConfig(cfg, env);
+  return cfg.remote;
+}
+
+async function syncArchive(options = {}, env = process.env) {
+  const cfg = loadConfig(env);
+  const mode = normalizeSyncMode(options["sync-mode"] || options.syncMode || options.mode || cfg.sync?.mode || "upload");
+  if (mode !== "upload") {
+    throw new Error(`remote sync mode "${mode}" is planned but not implemented yet; use upload mode to push this device without remote deletes`);
+  }
+  const lock = acquireSyncLock(env);
+  try {
+    const target = remoteTargetFromFlags(options, cfg, env);
+    if (target.protocol === "file") return syncArchiveToDirectory(target, options, env);
+    return syncArchiveToS3(target, options, env);
+  } finally {
+    releaseSyncLock(lock);
+  }
+}
+
+async function snapshotArchive(options = {}, env = process.env) {
+  return syncArchive({ ...options, snapshot: true, force: true }, env);
+}
+
+async function syncArchiveIfConfigured(env = process.env, options = {}) {
+  const cfg = loadConfig(env);
+  if (!hasRemoteTarget(cfg, env)) return { configured: false, scanned: 0, uploaded: 0, skipped: 0, errors: [] };
+  return syncArchive({ ...options, quiet: true }, env);
+}
+
+function hasRemoteTarget(cfg = loadConfig(), env = process.env) {
+  try {
+    remoteTargetFromFlags({}, cfg, env);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function remoteTargetFromFlags(flags = {}, cfg = loadConfig(), env = process.env, options = {}) {
+  const remote = cfg.remote || {};
+  let type = value(flags.type || flags.target || flags.storage || remote.type || cfg.storage?.backend || "r2");
+  let endpoint = value(
+    flags.endpoint ||
+      flags.remote ||
+      remote.endpoint ||
+      remote.url ||
+      env.AGENTLOG_REMOTE_ENDPOINT ||
+      env.R2_ENDPOINT ||
+      env.AWS_ENDPOINT_URL
+  );
+  let bucket = value(flags.bucket || remote.bucket || env.AGENTLOG_REMOTE_BUCKET || env.R2_BUCKET || env.AWS_BUCKET);
+  const normalized = normalizeRemoteEndpointInput(endpoint, bucket);
+  endpoint = normalized.endpoint;
+  bucket = normalized.bucket;
+  const region = value(flags.region || remote.region || env.AGENTLOG_REMOTE_REGION || env.AWS_REGION || (type === "r2" ? "auto" : "us-east-1"));
+  const prefix = normalizePrefix(value(flags.prefix || remote.prefix || env.AGENTLOG_REMOTE_PREFIX || "agentlog"));
+  const accessKeyId = value(
+    flags["access-key-id"] ||
+      flags.accessKeyId ||
+      remote.accessKeyId ||
+      env.AGENTLOG_REMOTE_ACCESS_KEY_ID ||
+      env.R2_ACCESS_KEY_ID ||
+      env.AWS_ACCESS_KEY_ID
+  );
+  const secretAccessKey = value(
+    flags["secret-access-key"] ||
+      flags.secretAccessKey ||
+      remote.secretAccessKey ||
+      env.AGENTLOG_REMOTE_SECRET_ACCESS_KEY ||
+      env.R2_SECRET_ACCESS_KEY ||
+      env.AWS_SECRET_ACCESS_KEY
+  );
+  if (type === "local" && endpoint) type = inferRemoteType(endpoint);
+
+  if (endpoint && endpoint.startsWith("file://")) {
+    return {
+      protocol: "file",
+      type,
+      endpoint,
+      root: fileUrlPath(endpoint),
+      prefix
+    };
+  }
+
+  if (!endpoint || !bucket) {
+    if (options.allowPartial) return { type, endpoint, bucket, region, prefix, accessKeyId, secretAccessKey };
+    throw new Error("remote sync requires --endpoint and --bucket, or matching AGENTLOG_REMOTE_* / R2_* / AWS_* settings");
+  }
+  if (!accessKeyId || !secretAccessKey) {
+    if (options.allowPartial) return { type, endpoint, bucket, region, prefix, accessKeyId, secretAccessKey };
+    throw new Error("remote sync requires --access-key-id and --secret-access-key, or matching AGENTLOG_REMOTE_* / R2_* / AWS_* settings");
+  }
+  const url = new URL(endpoint);
+  return { protocol: url.protocol.replace(":", ""), type, endpoint, url, bucket, region, prefix, accessKeyId, secretAccessKey };
+}
+
+async function syncArchiveToS3(target, options = {}, env = process.env) {
+  const cfg = loadConfig(env);
+  const objectPrefix = remoteObjectPrefix(target, cfg, options);
+  const localObjects = listLocalArchiveObjects(env, objectPrefix);
+  const state = loadSyncState(env);
+  const remoteObjects = await listS3Objects(target, objectPrefix);
+  const remoteByKey = new Map(remoteObjects.map((item) => [item.key, item]));
+  const summary = {
+    target: `${target.type}:${target.bucket}/${objectPrefix}`,
+    mode: "upload",
+    device: deviceLabel(cfg),
+    snapshot: Boolean(options.snapshot),
+    snapshotName: options.snapshot ? snapshotName(options) : "",
+    scanned: localObjects.length,
+    uploaded: 0,
+    skipped: 0,
+    retried: 0,
+    errors: []
+  };
+  reportSyncProgress(options, summary, 0, localObjects.length);
+
+  for (let index = 0; index < localObjects.length; index++) {
+    const object = localObjects[index];
+    const remote = remoteByKey.get(object.key);
+    const stateEntry = state.objects[object.key];
+    const unchangedRemote = remote && Number(remote.size) === object.size;
+    const unchangedState = stateEntry && stateEntry.fingerprint === object.fingerprint && unchangedRemote;
+    if (unchangedState || (unchangedRemote && !options.force)) {
+      summary.skipped++;
+      reportSyncProgress(options, summary, index + 1, localObjects.length, object.key);
+      continue;
+    }
+    if (options["dry-run"] || options.dryRun) {
+      summary.uploaded++;
+      reportSyncProgress(options, summary, index + 1, localObjects.length, object.key);
+      continue;
+    }
+    try {
+      const upload = await putS3ObjectWithRetry(target, object.key, fs.readFileSync(object.file), options);
+      summary.retried += upload.retried;
+      state.objects[object.key] = {
+        fingerprint: object.fingerprint,
+        size: object.size,
+        syncedAt: new Date().toISOString()
+      };
+      summary.uploaded++;
+    } catch (error) {
+      summary.errors.push(`${object.key}: ${error.message}`);
+    }
+    reportSyncProgress(options, summary, index + 1, localObjects.length, object.key);
+  }
+
+  if (!options["dry-run"] && !options.dryRun) saveSyncState(state, env);
+  return summary;
+}
+
+function syncArchiveToDirectory(target, options = {}, env = process.env) {
+  const cfg = loadConfig(env);
+  const objectPrefix = remoteObjectPrefix(target, cfg, options);
+  const localObjects = listLocalArchiveObjects(env, objectPrefix);
+  const root = path.join(target.root, objectPrefix);
+  const summary = {
+    target: pathToFileURL(root).href,
+    mode: "upload",
+    device: deviceLabel(cfg),
+    snapshot: Boolean(options.snapshot),
+    snapshotName: options.snapshot ? snapshotName(options) : "",
+    scanned: localObjects.length,
+    uploaded: 0,
+    skipped: 0,
+    retried: 0,
+    errors: []
+  };
+  reportSyncProgress(options, summary, 0, localObjects.length);
+  for (let index = 0; index < localObjects.length; index++) {
+    const object = localObjects[index];
+    const relative = stripPrefix(object.key, objectPrefix);
+    const dest = path.join(root, relative);
+    const existing = safeStat(dest);
+    if (existing && existing.size === object.size && !options.force) {
+      summary.skipped++;
+      reportSyncProgress(options, summary, index + 1, localObjects.length, object.key);
+      continue;
+    }
+    if (options["dry-run"] || options.dryRun) {
+      summary.uploaded++;
+      reportSyncProgress(options, summary, index + 1, localObjects.length, object.key);
+      continue;
+    }
+    try {
+      ensureDir(path.dirname(dest));
+      fs.copyFileSync(object.file, dest);
+      summary.uploaded++;
+    } catch (error) {
+      summary.errors.push(`${object.key}: ${error.message}`);
+    }
+    reportSyncProgress(options, summary, index + 1, localObjects.length, object.key);
+  }
+  return summary;
+}
+
+function listLocalArchiveObjects(env = process.env, prefix = "agentlog") {
+  const root = archiveRoot(env);
+  const objects = [];
+  walk(root, (file) => {
+    const stat = safeStat(file);
+    if (!stat || !stat.isFile()) return;
+    const relative = path.relative(root, file).split(path.sep).join("/");
+    const key = [normalizePrefix(prefix), relative].filter(Boolean).join("/");
+    objects.push({
+      file,
+      key,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      fingerprint: `${stat.size}:${Math.floor(stat.mtimeMs)}`
+    });
+  });
+  return objects.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+async function listS3Objects(target, prefix) {
+  const objects = [];
+  let continuationToken = "";
+  for (;;) {
+    const query = {
+      "list-type": "2",
+      prefix
+    };
+    if (continuationToken) query["continuation-token"] = continuationToken;
+    const response = await s3Request(target, { method: "GET", query });
+    if (response.statusCode >= 300) throw new Error(`list remote objects failed (${response.statusCode}): ${response.body.toString("utf8")}`);
+    const parsed = parseListBucketResult(response.body.toString("utf8"));
+    objects.push(...parsed.objects);
+    if (!parsed.isTruncated || !parsed.nextContinuationToken) break;
+    continuationToken = parsed.nextContinuationToken;
+  }
+  return objects;
+}
+
+async function putS3Object(target, key, body) {
+  const response = await s3Request(target, {
+    method: "PUT",
+    key,
+    body,
+    headers: {
+      "content-type": contentTypeForKey(key)
+    }
+  });
+  if (response.statusCode >= 300) throw new Error(`upload failed (${response.statusCode}): ${response.body.toString("utf8")}`);
+  return response;
+}
+
+async function putS3ObjectWithRetry(target, key, body, options = {}) {
+  const maxAttempts = Math.max(1, Number(options.retries || options["retries"] || 3));
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await putS3Object(target, key, body);
+      return { retried: attempt - 1 };
+    } catch (error) {
+      lastError = error;
+      if (attempt >= maxAttempts || !isRetryableUploadError(error)) break;
+      await delay(Math.min(250 * 2 ** (attempt - 1), 2000));
+    }
+  }
+  throw lastError;
+}
+
+function s3Request(target, request) {
+  const body = Buffer.isBuffer(request.body) ? request.body : Buffer.from(request.body || "");
+  const method = request.method || "GET";
+  const key = request.key || "";
+  const query = request.query || {};
+  const pathName = s3Path(target.bucket, key);
+  const now = new Date();
+  const headers = {
+    host: target.url.host,
+    "x-amz-content-sha256": sha256Hex(body),
+    "x-amz-date": amzDate(now),
+    ...(request.headers || {})
+  };
+  if (body.length) headers["content-length"] = String(body.length);
+  headers.authorization = authorizationHeader({ target, method, pathName, query, headers, now });
+
+  return new Promise((resolve, reject) => {
+    const transport = target.url.protocol === "http:" ? http : https;
+    const req = transport.request(
+      {
+        protocol: target.url.protocol,
+        hostname: target.url.hostname,
+        port: target.url.port || undefined,
+        method,
+        path: pathName + canonicalQueryString(query, true),
+        headers
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolve({ statusCode: res.statusCode || 0, headers: res.headers, body: Buffer.concat(chunks) }));
+      }
+    );
+    req.on("error", reject);
+    if (body.length) req.write(body);
+    req.end();
+  });
+}
+
+function authorizationHeader({ target, method, pathName, query, headers, now }) {
+  const signedHeaderNames = Object.keys(headers).map((name) => name.toLowerCase()).sort();
+  const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${String(headers[name] ?? headers[Object.keys(headers).find((key) => key.toLowerCase() === name)]).trim()}\n`).join("");
+  const signedHeaders = signedHeaderNames.join(";");
+  const requestHash = sha256Hex(
+    [
+      method,
+      pathName,
+      canonicalQueryString(query, false),
+      canonicalHeaders,
+      signedHeaders,
+      headers["x-amz-content-sha256"]
+    ].join("\n")
+  );
+  const date = amzDate(now).slice(0, 8);
+  const scope = `${date}/${target.region}/s3/aws4_request`;
+  const stringToSign = ["AWS4-HMAC-SHA256", amzDate(now), scope, requestHash].join("\n");
+  const signature = hmacHex(signingKey(target.secretAccessKey, date, target.region), stringToSign);
+  return `AWS4-HMAC-SHA256 Credential=${target.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+}
+
+function signingKey(secret, date, region) {
+  const kDate = hmac(Buffer.from(`AWS4${secret}`, "utf8"), date);
+  const kRegion = hmac(kDate, region);
+  const kService = hmac(kRegion, "s3");
+  return hmac(kService, "aws4_request");
+}
+
+function s3Path(bucket, key = "") {
+  const segments = [bucket, ...String(key || "").split("/").filter(Boolean)];
+  return `/${segments.map(awsEncode).join("/")}`;
+}
+
+function canonicalQueryString(query = {}, includePrefix = false) {
+  const entries = Object.entries(query)
+    .filter(([, value]) => value != null && value !== "")
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `${awsEncode(key)}=${awsEncode(value)}`)
+    .join("&");
+  if (!includePrefix) return entries;
+  return entries ? `?${entries}` : "";
+}
+
+function awsEncode(value) {
+  return encodeURIComponent(String(value)).replace(/[!'()*]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function parseListBucketResult(xml) {
+  const objects = [];
+  for (const match of String(xml || "").matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
+    const block = match[1];
+    const key = xmlValue(block, "Key");
+    if (!key) continue;
+    objects.push({
+      key,
+      size: Number(xmlValue(block, "Size") || 0),
+      etag: xmlValue(block, "ETag").replace(/^"|"$/g, ""),
+      lastModified: xmlValue(block, "LastModified")
+    });
+  }
+  return {
+    objects,
+    isTruncated: xmlValue(xml, "IsTruncated") === "true",
+    nextContinuationToken: xmlValue(xml, "NextContinuationToken")
+  };
+}
+
+function xmlValue(xml, name) {
+  const match = String(xml || "").match(new RegExp(`<${name}>([\\s\\S]*?)<\\/${name}>`));
+  return match ? decodeXml(match[1]) : "";
+}
+
+function decodeXml(value) {
+  return String(value || "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function reportSyncProgress(options, summary, current, total, key = "") {
+  if (typeof options.onProgress !== "function") return;
+  options.onProgress({
+    kind: "sync",
+    provider: "Remote Sync",
+    current,
+    total,
+    uploaded: summary.uploaded,
+    skipped: summary.skipped,
+    retried: summary.retried || 0,
+    errors: summary.errors.length,
+    message: `uploaded=${summary.uploaded} current=${summary.skipped}${summary.retried ? ` retried=${summary.retried}` : ""} errors=${summary.errors.length}`,
+    path: key
+  });
+}
+
+function loadSyncState(env = process.env) {
+  return readJson(path.join(paths(env).state, "sync.json"), { objects: {} });
+}
+
+function saveSyncState(state, env = process.env) {
+  writeJson(path.join(paths(env).state, "sync.json"), state);
+}
+
+function readJsonMaybe(file, fallback) {
+  try {
+    return readJson(file, fallback);
+  } catch {
+    return fallback;
+  }
+}
+
+function acquireSyncLock(env = process.env) {
+  const p = paths(env);
+  ensureDir(p.state);
+  const file = path.join(p.state, "sync.lock");
+  const payload = {
+    pid: process.pid,
+    startedAt: new Date().toISOString()
+  };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(file, "wx", 0o600);
+      fs.writeFileSync(fd, `${JSON.stringify(payload)}\n`);
+      fs.closeSync(fd);
+      return { file, pid: process.pid };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const existing = readJsonMaybe(file, null);
+      if (isStaleSyncLock(existing)) {
+        safeUnlink(file);
+        continue;
+      }
+      const owner = existing?.pid ? `PID ${existing.pid}` : "another process";
+      throw new Error(`remote sync is already running (${owner}); wait for it to finish, then run agentlog sync again`);
+    }
+  }
+  throw new Error("remote sync is already running; wait for it to finish, then run agentlog sync again");
+}
+
+function releaseSyncLock(lock) {
+  if (!lock?.file) return;
+  const existing = readJsonMaybe(lock.file, null);
+  if (!existing?.pid || Number(existing.pid) === process.pid) safeUnlink(lock.file);
+}
+
+function isStaleSyncLock(lock) {
+  if (!lock || typeof lock !== "object") return true;
+  const pid = Number(lock.pid);
+  if (!pid || !isProcessAlive(pid)) return true;
+  const started = new Date(lock.startedAt || 0);
+  if (Number.isNaN(started.getTime())) return false;
+  return Date.now() - started.getTime() > 6 * 60 * 60 * 1000;
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function contentTypeForKey(key) {
+  if (key.endsWith(".json") || key.endsWith(".jsonl")) return "application/json";
+  if (key.endsWith(".md") || key.endsWith(".markdown")) return "text/markdown; charset=utf-8";
+  return "application/octet-stream";
+}
+
+function isRetryableUploadError(error) {
+  const message = String(error?.message || "");
+  const code = String(error?.code || "");
+  if (["EPIPE", "ECONNRESET", "ETIMEDOUT", "ECONNREFUSED", "EAI_AGAIN"].includes(code)) return true;
+  if (/EPIPE|ECONNRESET|ETIMEDOUT|socket hang up|bad record mac|tls alert|SSL routines/i.test(message)) return true;
+  const status = message.match(/\((\d{3})\)/)?.[1];
+  return status ? Number(status) === 429 || Number(status) >= 500 : false;
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function walk(dir, visit) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, visit);
+    else visit(full);
+  }
+}
+
+function safeStat(file) {
+  try {
+    return fs.statSync(file);
+  } catch {
+    return null;
+  }
+}
+
+function safeUnlink(file) {
+  try {
+    fs.unlinkSync(file);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+function stripPrefix(key, prefix) {
+  const normalized = normalizePrefix(prefix);
+  return normalized && key.startsWith(`${normalized}/`) ? key.slice(normalized.length + 1) : key;
+}
+
+function normalizePrefix(prefix) {
+  return String(prefix || "").replace(/^\/+|\/+$/g, "");
+}
+
+function remoteObjectPrefix(target, cfg = {}, options = {}) {
+  const prefix = normalizePrefix(target.prefix || "agentlog");
+  if (options.snapshot) return [prefix, "snapshots", snapshotName(options), deviceSlug(cfg)].filter(Boolean).join("/");
+  return [prefix, "devices", deviceSlug(cfg)].filter(Boolean).join("/");
+}
+
+function snapshotName(options = {}) {
+  const explicit = value(options["snapshot-name"] || options.snapshotName || options.name);
+  if (explicit) return slugifyRemoteSegment(explicit);
+  if (!options._snapshotName) {
+    options._snapshotName = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  }
+  return options._snapshotName;
+}
+
+function deviceSlug(cfg = {}) {
+  return slugifyRemoteSegment(cfg.device?.slug || cfg.device?.name || cfg.device?.id || "this-device");
+}
+
+function deviceLabel(cfg = {}) {
+  const name = value(cfg.device?.name || "");
+  const slug = deviceSlug(cfg);
+  return name && name !== slug ? `${name} (${slug})` : slug;
+}
+
+function slugifyRemoteSegment(value) {
+  return String(value || "this-device")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96) || "this-device";
+}
+
+function normalizeSyncMode(value) {
+  const normalized = String(value || "upload").trim().toLowerCase();
+  return {
+    "upload-only": "upload",
+    upload: "upload",
+    push: "upload",
+    "two-way": "two-way",
+    twoway: "two-way",
+    bidirectional: "two-way",
+    receive: "receive",
+    "receive-only": "receive",
+    pull: "receive"
+  }[normalized] || normalized;
+}
+
+function normalizeSyncInterval(value) {
+  if (String(value || "").trim().toLowerCase() === "manual") return 0;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) return 30;
+  return Math.round(number);
+}
+
+function fileUrlPath(endpoint) {
+  return fileURLToPath(endpoint);
+}
+
+function value(input) {
+  return String(input || "").trim();
+}
+
+function inferRemoteType(endpoint) {
+  const value = String(endpoint || "").toLowerCase();
+  if (value.startsWith("file://")) return "custom";
+  if (value.includes("r2.cloudflarestorage.com")) return "r2";
+  if (value.includes("amazonaws.com")) return "s3";
+  return "custom";
+}
+
+function sha256Hex(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function hmac(key, value) {
+  return crypto.createHmac("sha256", key).update(value).digest();
+}
+
+function hmacHex(key, value) {
+  return crypto.createHmac("sha256", key).update(value).digest("hex");
+}
+
+function amzDate(date) {
+  return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+
+module.exports = {
+  configureRemoteFromFlags,
+  hasRemoteTarget,
+  listLocalArchiveObjects,
+  parseListBucketResult,
+  remoteTargetFromFlags,
+  remoteObjectPrefix,
+  snapshotArchive,
+  syncArchive,
+  syncArchiveIfConfigured
+};

package/src/version.js

@@ -0,0 +1,7 @@
+"use strict";
+
+const { version } = require("../package.json");
+
+module.exports = {
+  version
+};