lua-cli 3.15.2 → 3.16.0

package/dist/utils/backup-helpers.js

@@ -1,827 +0,0 @@
-/**
- * Backup Helper Utilities
- *
- * Utilities for project backup operations using S3 blob storage.
- * Content is stored in S3, keyed by content hash for deduplication.
- */
-import fs from 'fs';
-import path from 'path';
-import crypto from 'crypto';
-import zlib from 'zlib';
-// The compiler writes 16-char truncated SHA-256 hashes for project files into
-// `manifest.projectFiles[].hash`. Those hashes flow into the backup manifest
-// (via `prepareFileRefs`) and the local cache (via `writeBackupManifestCache`).
-// For the conflict detector to compare like-with-like, disk hashes must use
-// the same truncation. Importing the compiler's helper directly binds us to
-// that single source of truth — if the compiler ever changes the format, the
-// detector moves with it automatically. Do NOT swap this for the `hashContent`
-// defined below in this file, which returns full 64-char hashes for a
-// different purpose (project-level combined hash).
-import { hashContent as hashProjectFile } from '../compiler/utils/common.js';
-import { COMPILE_DIRS } from '../config/compile.constants.js';
-import { loadManifest, hasCompilationOutput } from './artifact-loader.js';
-import BackupApi from '../api/backup.api.service.js';
-import { BASE_URLS } from '../config/constants.js';
-// Cache records the file list + hashes from this machine's last successful
-// `lua push backup`. The server does not expose historical manifests, so
-// `lua sync --pull`'s conflict guard relies on this local record.
-const BACKUP_CACHE_FILENAME = 'backup-manifest.json';
-// =============================================================================
-// HASH CALCULATION
-// =============================================================================
-/**
- * Calculate a hash for a string content.
- *
- * @param content - The content to hash
- * @returns SHA-256 hash as hex string
- */
-export function hashContent(content) {
-    return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
-}
-/**
- * Calculate combined project hash from all project files.
- * This hash is used to detect if the project has changed since last backup.
- *
- * @param projectFiles - Array of project files from the manifest
- * @returns Combined hash of all file hashes (sorted for determinism)
- */
-export function calculateProjectHash(projectFiles) {
-    // Sort by relative path for deterministic ordering
-    const sortedFiles = [...projectFiles].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-    // Combine all individual file hashes
-    const combinedHashes = sortedFiles.map((f) => f.hash).join('|');
-    return hashContent(combinedHashes);
-}
-/**
- * Get the current project hash from the compilation manifest.
- * Returns null if no manifest exists.
- *
- * @param projectPath - Path to the project root
- * @returns The project hash or null
- */
-export function getCurrentProjectHash(projectPath = process.cwd()) {
-    if (!hasCompilationOutput(projectPath))
-        return null;
-    const manifest = loadManifest(projectPath);
-    return calculateProjectHash(manifest.projectFiles);
-}
-// =============================================================================
-// SOURCE LOADING
-// =============================================================================
-/**
- * Load all project source files from dist-v2/sources/ directory.
- *
- * @param manifest - The compilation manifest
- * @param projectPath - Path to the project root
- * @returns Map of relative path -> file content
- */
-export function loadProjectSources(manifest, projectPath = process.cwd()) {
-    const sourcesDir = path.join(projectPath, COMPILE_DIRS.DIST_V2, 'sources');
-    const sources = new Map();
-    for (const file of manifest.projectFiles) {
-        const ext = path.extname(file.relativePath) || '.txt';
-        const sourcePath = path.join(sourcesDir, `${file.hash}${ext}`);
-        if (fs.existsSync(sourcePath)) {
-            const content = fs.readFileSync(sourcePath, 'utf-8');
-            sources.set(file.relativePath, content);
-        }
-    }
-    return sources;
-}
-/**
- * Load source content by hash from dist-v2/sources/ directory.
- *
- * @param hash - The content hash
- * @param relativePath - Original relative path (for extension)
- * @param projectPath - Path to the project root
- * @returns The file content or null if not found
- */
-export function loadSourceByHash(hash, relativePath, projectPath = process.cwd()) {
-    const sourcesDir = path.join(projectPath, COMPILE_DIRS.DIST_V2, 'sources');
-    const ext = path.extname(relativePath) || '.txt';
-    const sourcePath = path.join(sourcesDir, `${hash}${ext}`);
-    if (fs.existsSync(sourcePath)) {
-        return fs.readFileSync(sourcePath, 'utf-8');
-    }
-    return null;
-}
-// =============================================================================
-// BLOB PREPARATION
-// =============================================================================
-/**
- * Prepare file references (manifest entries) from the compilation output.
- * No content included - just metadata for the manifest.
- *
- * @param projectPath - Path to the project root
- * @returns Array of file references ready for manifest
- */
-export function prepareFileRefs(projectPath = process.cwd()) {
-    const manifest = loadManifest(projectPath);
-    return manifest.projectFiles.map((file) => ({
-        relativePath: file.relativePath,
-        hash: file.hash,
-        size: file.size,
-        type: file.type,
-        ...(file.external ? { external: true } : {}),
-    }));
-}
-/**
- * Reconcile `manifest.projectFiles` and `dist-v2/sources/` with the
- * current on-disk state of each file. Fixes the pre-existing gap where
- * compile's yaml-sync step rewrites `lua.skill.yaml` on disk AFTER the
- * manifest was produced, leaving the manifest's hash for that file
- * one bump behind disk. `pushBackupCommand` calls this before using
- * the manifest so cache, uploaded blobs, and computed project hash all
- * describe disk-as-it-is-now.
- *
- * Approach: iterate manifest.projectFiles, re-hash each from disk. For
- * any file whose disk hash differs from the manifest hash, write a
- * matching blob into sources/ under the new hash (so uploadBlobsToS3
- * still finds content for the hash it's asked to upload) and update
- * the manifest entry. Persist the manifest to disk at the end if
- * anything changed. Orphaned old-hash files in sources/ are left in
- * place — they're gitignored and clean up naturally on the next
- * `npm run clean` or `lua compile`.
- *
- * Lenient: if a file in the manifest no longer exists on disk (user
- * deleted), skip it; the next compile will drop it from the manifest.
- */
-export function reconcileManifestWithDisk(projectPath = process.cwd()) {
-    const manifestPath = path.join(projectPath, COMPILE_DIRS.DIST_V2, 'manifest.json');
-    if (!fs.existsSync(manifestPath))
-        return;
-    const manifest = loadManifest(projectPath);
-    const sourcesDir = path.join(projectPath, COMPILE_DIRS.DIST_V2, 'sources');
-    fs.mkdirSync(sourcesDir, { recursive: true });
-    let changed = false;
-    for (const file of manifest.projectFiles) {
-        // External files live outside `projectPath` and aren't rewritten by
-        // compile's yaml-sync step, so there's nothing for the reconciler
-        // to fix. Their hash was computed from disk at compile time and
-        // already matches the manifest.
-        if (file.external)
-            continue;
-        const absPath = path.join(projectPath, file.relativePath);
-        if (!fs.existsSync(absPath))
-            continue;
-        let content;
-        try {
-            content = fs.readFileSync(absPath, 'utf-8');
-        }
-        catch {
-            continue; // unreadable; let a later compile handle it
-        }
-        const freshHash = hashProjectFile(content);
-        if (freshHash === file.hash)
-            continue;
-        // Drop new blob into sources/ under the fresh hash so the existing
-        // upload pipeline (keyed by hash → sources/<hash>.<ext>) can find it.
-        const ext = path.extname(file.relativePath) || '.txt';
-        const sourceTargetPath = path.join(sourcesDir, `${freshHash}${ext}`);
-        try {
-            fs.writeFileSync(sourceTargetPath, content, 'utf-8');
-        }
-        catch {
-            continue; // best-effort; skip this file
-        }
-        file.hash = freshHash;
-        file.size = Buffer.byteLength(content, 'utf-8');
-        changed = true;
-    }
-    if (changed) {
-        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
-    }
-}
-/**
- * Upload blobs directly to S3 using presigned URLs.
- * Compresses content with gzip before upload to reduce storage costs.
- *
- * @param uploadUrls - Map of hash -> presigned S3 PUT URL
- * @param manifest - The compilation manifest (for resolving hash → relativePath)
- * @param projectPath - Path to the project root
- * @param onProgress - Optional callback for progress updates
- * @param concurrency - Maximum parallel uploads (default: 10)
- * @returns Number of blobs uploaded
- */
-export async function uploadBlobsToS3(uploadUrls, manifest, projectPath = process.cwd(), onProgress, concurrency = 10) {
-    const hashes = Object.keys(uploadUrls);
-    const hashToRelativePath = buildHashToRelativePathMap(manifest);
-    let uploaded = 0;
-    for (let i = 0; i < hashes.length; i += concurrency) {
-        const batch = hashes.slice(i, i + concurrency);
-        await Promise.all(batch.map(async (hash) => {
-            const relativePath = hashToRelativePath.get(hash);
-            if (!relativePath) {
-                throw new Error(`No file found in manifest for hash: ${hash}`);
-            }
-            const content = loadSourceByHash(hash, relativePath, projectPath);
-            if (!content) {
-                throw new Error(`Source file not found for hash: ${hash} (${relativePath})`);
-            }
-            // Gzip compress before upload
-            const compressed = zlib.gzipSync(Buffer.from(content, 'utf-8'));
-            // PUT directly to S3 presigned URL
-            const response = await fetch(uploadUrls[hash], {
-                method: 'PUT',
-                body: compressed,
-                headers: { 'Content-Type': 'application/octet-stream' },
-            });
-            if (!response.ok) {
-                throw new Error(`S3 upload failed for ${hash.substring(0, 12)}...: ${response.status} ${response.statusText}`);
-            }
-        }));
-        uploaded += batch.length;
-        onProgress?.(uploaded, hashes.length);
-    }
-    return uploaded;
-}
-/**
- * Build a map from content hash to the first matching relative path.
- * Used by uploadBlobsToS3 to resolve file extensions for loadSourceByHash.
- */
-function buildHashToRelativePathMap(manifest) {
-    const map = new Map();
-    for (const file of manifest.projectFiles) {
-        if (!map.has(file.hash)) {
-            map.set(file.hash, file.relativePath);
-        }
-    }
-    return map;
-}
-/**
- * Get all unique hashes from the manifest.
- *
- * @param projectPath - Path to the project root
- * @returns Array of unique content hashes
- */
-export function getAllFileHashes(projectPath = process.cwd()) {
-    const manifest = loadManifest(projectPath);
-    // Use Set to deduplicate (same content may appear multiple times)
-    return [...new Set(manifest.projectFiles.map((f) => f.hash))];
-}
-// =============================================================================
-// BLOB DOWNLOAD
-// =============================================================================
-/**
- * Download a blob from a presigned URL.
- * Decompresses gzip content (blobs are stored compressed in S3).
- *
- * @param url - The presigned S3 URL
- * @returns The decompressed blob content as a Buffer
- */
-async function downloadBlobFromUrl(url) {
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new Error(`Failed to download blob: ${response.status} ${response.statusText}`);
-    }
-    const arrayBuffer = await response.arrayBuffer();
-    const buffer = Buffer.from(arrayBuffer);
-    // Detect gzip via magic bytes (1f 8b). Most blobs are gzip-compressed
-    // (CLI/server convention), but legacy/older uploads may be raw — fall
-    // back to the raw buffer rather than throwing the whole restore.
-    if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
-        try {
-            return zlib.gunzipSync(buffer);
-        }
-        catch {
-            // Looked like gzip but failed to decompress — fall through to raw
-        }
-    }
-    return buffer;
-}
-/**
- * Download multiple blobs in parallel from presigned URLs.
- *
- * @param urls - Map of hash -> presigned URL
- * @param concurrency - Maximum number of parallel downloads (default: 10)
- * @returns Map of hash -> content buffer
- */
-export async function downloadBlobsParallel(urls, concurrency = 10) {
-    const results = new Map();
-    const entries = Object.entries(urls);
-    // Download in batches
-    for (let i = 0; i < entries.length; i += concurrency) {
-        const batch = entries.slice(i, i + concurrency);
-        const batchResults = await Promise.all(batch.map(async ([hash, url]) => {
-            const content = await downloadBlobFromUrl(url);
-            return { hash, content };
-        }));
-        for (const { hash, content } of batchResults) {
-            results.set(hash, content);
-        }
-    }
-    return results;
-}
-// =============================================================================
-// PROJECT RESTORATION
-// =============================================================================
-/**
- * Restore project files from a backup manifest and downloaded blobs.
- * Creates all directories and files in the target directory.
- *
- * @param manifest - The backup manifest (file references)
- * @param blobs - Map of hash -> content buffer (downloaded blobs)
- * @param targetDir - Target directory to restore to
- * @param options - Optional settings
- */
-export function restoreProjectFromBackup(manifest, blobs, targetDir, options = {}) {
-    const { overwrite = false } = options;
-    for (const file of manifest.files) {
-        const filePath = resolveBackupFileTarget(file, targetDir);
-        const fileDir = path.dirname(filePath);
-        // Skip if file exists and overwrite is false
-        if (fs.existsSync(filePath) && !overwrite) {
-            continue;
-        }
-        // Get blob content
-        const content = blobs.get(file.hash);
-        if (!content) {
-            throw new Error(`Blob not found for hash: ${file.hash} (${file.relativePath})`);
-        }
-        fs.mkdirSync(fileDir, { recursive: true });
-        fs.writeFileSync(filePath, content);
-    }
-}
-/**
- * Resolve where a single backup entry should land on disk during restore.
- *
- * In-project entries are written at `targetDir/<relativePath>`. External
- * entries (cross-root workspace files captured for BAC-69) are sandboxed
- * under `targetDir/.lua/external/<relativePath>` — we never write them
- * back to their original workspace location, because:
- *
- *   1. The target dir might not even be a monorepo (`lua init --from-server`
- *      clones the agent alone), in which case the original path doesn't
- *      exist.
- *   2. Writing outside `targetDir` is a footgun: sibling packages may
- *      still contain local edits we don't want to clobber.
- *
- * `.lua/external/` is a stable, gitignored mirror the compiler can read
- * from at rebuild time and the human can inspect to see what the backup
- * actually brought along.
- *
- * Defense-in-depth: we also reject paths that would escape `targetDir`
- * after sandboxing, so a malicious manifest with `../` segments can't
- * write outside the project tree.
- */
-export function resolveBackupFileTarget(file, targetDir) {
-    const base = path.resolve(targetDir);
-    const sandboxed = file.external
-        ? path.join(base, '.lua', 'external', file.relativePath)
-        : path.join(base, file.relativePath);
-    const resolved = path.resolve(sandboxed);
-    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
-        throw new Error(`Backup entry escapes target directory: ${file.relativePath}`);
-    }
-    return resolved;
-}
-/**
- * Check which files would be created/overwritten by restore.
- * Useful for showing user what will happen before restore.
- *
- * @param manifest - The backup manifest
- * @param targetDir - Target directory to check against
- * @returns Object with new files, existing files, and total count
- */
-export function checkRestoreConflicts(manifest, targetDir) {
-    const newFiles = [];
-    const existingFiles = [];
-    for (const file of manifest.files) {
-        const filePath = resolveBackupFileTarget(file, targetDir);
-        if (fs.existsSync(filePath)) {
-            existingFiles.push(file.relativePath);
-        }
-        else {
-            newFiles.push(file.relativePath);
-        }
-    }
-    return {
-        newFiles,
-        existingFiles,
-        totalFiles: manifest.files.length,
-    };
-}
-// =============================================================================
-// BACKUP TRACKING
-// =============================================================================
-/**
- * Check if project backup is out of sync (local changes not pushed).
- *
- * @param currentHash - Current project hash from manifest
- * @param tracking - Backup tracking from YAML
- * @returns true if backup is out of sync
- */
-export function isBackupOutOfSync(currentHash, tracking) {
-    if (!tracking?.lastHash)
-        return true;
-    return tracking.lastHash !== currentHash;
-}
-/**
- * Create backup tracking object after successful push.
- *
- * @param projectHash - The hash of the pushed backup
- * @returns YamlConfigBackup object for storing in YAML
- */
-export function createBackupTracking(projectHash) {
-    return {
-        lastHash: projectHash,
-        lastPushedAt: new Date().toISOString(),
-    };
-}
-// =============================================================================
-// LOCAL BACKUP MANIFEST CACHE
-// =============================================================================
-export function getBackupCachePath(projectPath = process.cwd()) {
-    return path.join(projectPath, '.lua', BACKUP_CACHE_FILENAME);
-}
-// Best-effort: a failed write must not fail the push that just succeeded
-// on the server. A missing cache degrades `lua sync --pull` to its
-// lenient "no-tracking" path.
-export function writeBackupManifestCache(cache, projectPath = process.cwd()) {
-    const cachePath = getBackupCachePath(projectPath);
-    try {
-        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
-        fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.warn(`Could not write backup manifest cache: ${message}`);
-    }
-}
-// Returns null when the cache is missing, unreadable, or malformed — the
-// conflict guard treats null as the "no-tracking" signal.
-export function readBackupManifestCache(projectPath = process.cwd()) {
-    const cachePath = getBackupCachePath(projectPath);
-    if (!fs.existsSync(cachePath))
-        return null;
-    try {
-        const raw = fs.readFileSync(cachePath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        // Guard against hand-edits or version skew, not against our own writer.
-        if (typeof parsed.lastHash !== 'string' ||
-            typeof parsed.lastPushedAt !== 'string' ||
-            !Array.isArray(parsed.files) ||
-            !parsed.files.every((f) => f && typeof f.relativePath === 'string' && typeof f.hash === 'string')) {
-            return null;
-        }
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-// Files that `compileCommand()` silently rewrites as a side effect of
-// its server-sync step (currently just `lua.skill.yaml`, which the
-// handlers' `applySyncToYaml` bumps to match the server's active
-// primitive versions). `syncCommand` runs compile at the top, so when
-// the guard hashes disk after compile, yaml bytes already differ from
-// the last-push cache even if the user hasn't edited anything.
-//
-// Skipping yaml here avoids a false-positive `Refusing to pull` abort
-// on every multi-machine pull. The file is generated by compile, is
-// restored from backup during the pull, and any real divergence is
-// reconciled by `pushBackupCommand`'s `reconcileManifestWithDisk`
-// before the next backup is pushed.
-const COMPILE_MANAGED_FILES = new Set(['lua.skill.yaml']);
-// Algorithm matches spec 2026-04-15-sync-pull-conflict-guard-design.md.
-export function detectLocalConflictsForPull(incomingFiles, projectPath = process.cwd()) {
-    const cache = readBackupManifestCache(projectPath);
-    if (!cache) {
-        return { conflicts: [], warning: 'no-tracking' };
-    }
-    const cachedByPath = new Map(cache.files.map((f) => [f.relativePath, f.hash]));
-    const conflicts = new Set();
-    const projectRoot = path.resolve(projectPath);
-    for (const incoming of incomingFiles) {
-        // Skip files compile silently rewrites; see COMPILE_MANAGED_FILES.
-        if (COMPILE_MANAGED_FILES.has(incoming.relativePath))
-            continue;
-        // External (cross-root) files are restored into `.lua/external/`, not
-        // back to their workspace origin, so they can never conflict with an
-        // in-project file the user is editing. Skip them.
-        if (incoming.external)
-            continue;
-        const absPath = path.resolve(projectRoot, incoming.relativePath);
-        // Defense-in-depth: skip manifest entries whose path escapes the project
-        // directory (e.g. via `../`). The restore step is the real vulnerability
-        // surface here; silently skipping keeps the guard from hashing arbitrary
-        // files outside the project.
-        if (absPath !== projectRoot && !absPath.startsWith(projectRoot + path.sep)) {
-            continue;
-        }
-        if (!fs.existsSync(absPath))
-            continue;
-        let diskHash;
-        try {
-            const bytes = fs.readFileSync(absPath, 'utf-8');
-            // Must match the compiler's hash format — the cache and server manifest
-            // both contain 16-char truncated hashes (see hashProjectFile import above).
-            diskHash = hashProjectFile(bytes);
-        }
-        catch {
-            // Unreadable: flag as conflict so we don't silently overwrite.
-            conflicts.add(incoming.relativePath);
-            continue;
-        }
-        const cachedHash = cachedByPath.get(incoming.relativePath);
-        if (cachedHash !== undefined) {
-            if (diskHash !== cachedHash) {
-                conflicts.add(incoming.relativePath);
-            }
-            continue;
-        }
-        // Not in local cache — user created this file or pushed from a
-        // different machine. Flag only if pulling would actually change it.
-        if (diskHash !== incoming.hash) {
-            conflicts.add(incoming.relativePath);
-        }
-    }
-    return { conflicts: [...conflicts].sort(), warning: null };
-}
-// =============================================================================
-// SYNC HELPERS
-// =============================================================================
-// Fetch the current backup manifest for sync's pre-pull conflict guard.
-// Returns `fetched: null` when the request fails so the caller can warn
-// about lenient-mode fallback without pattern-matching on exceptions.
-export async function fetchBackupManifestForPull(apiKey, agentId) {
-    try {
-        const backupApi = new BackupApi(BASE_URLS.API, apiKey, agentId);
-        const response = await backupApi.getBackupManifest();
-        return { fetched: response.data ?? null };
-    }
-    catch {
-        return { fetched: null };
-    }
-}
-/**
- * Pure freshness-decision logic for `checkServerBackupNewerThanLocal`.
- * Exported so tests can exercise every branch (no-cache, server-fetch-
- * failed, server-newer, server-older) without mocking HTTP.
- *
- * Uses `projectHash` as the freshness signal, not `createdAt`: the
- * server's `BackupMetadata.createdAt` is the date the backup RECORD was
- * first created (often days/weeks ago), not the last time it was
- * updated. Comparing our local `lastPushedAt` to the record's
- * `createdAt` produces wrong answers; comparing the project hashes
- * answers the actual question ("did anyone push something I haven't
- * seen?").
- *
- * Lenient: missing local cache → proceed (no baseline); missing server
- * metadata → `checkFailed` so callers can warn-and-proceed rather than
- * block on transient server errors.
- */
-export function decideBackupFreshness(local, serverMetadata) {
-    if (!local)
-        return { serverNewer: false };
-    if (!serverMetadata)
-        return { serverNewer: false, checkFailed: true };
-    // If the server's current backup hash differs from the hash we last
-    // pushed, someone else pushed in between — refuse unless --force.
-    // Equal hashes mean nothing has changed server-side; a re-push of
-    // the same content is harmless (skipped by the later up-to-date
-    // check anyway).
-    const serverNewer = serverMetadata.projectHash !== local.lastHash;
-    return {
-        serverNewer,
-        serverProjectHash: serverMetadata.projectHash,
-        localLastHash: local.lastHash,
-    };
-}
-/**
- * Compare the server's backup `createdAt` to this machine's local cache
- * `lastPushedAt`. Used to detect the "another machine pushed while I
- * wasn't looking" case before `lua push backup` uploads and overwrites
- * the server side.
- */
-export async function checkServerBackupNewerThanLocal(apiKey, agentId, projectPath = process.cwd()) {
-    const local = readBackupManifestCache(projectPath);
-    try {
-        const api = new BackupApi(BASE_URLS.API, apiKey, agentId);
-        const resp = await api.getBackupMetadata();
-        const metadata = resp.success && resp.data ? { projectHash: resp.data.projectHash } : null;
-        return decideBackupFreshness(local, metadata);
-    }
-    catch {
-        return decideBackupFreshness(local, null);
-    }
-}
-/**
- * Check whether a backup exists for the given agent.
- * Returns availability status along with basic metadata if a backup is found.
- *
- * @param apiKey - API key for authentication
- * @param agentId - The agent whose backup to check
- * @returns Object indicating availability and optional metadata
- */
-export async function checkBackupAvailability(apiKey, agentId) {
-    try {
-        const backupApi = new BackupApi(BASE_URLS.API, apiKey, agentId);
-        const metadata = await backupApi.getBackupMetadata();
-        if (metadata.data && metadata.data.fileCount > 0) {
-            return {
-                available: true,
-                fileCount: metadata.data.fileCount,
-                lastPushedAt: metadata.data.createdAt,
-            };
-        }
-        return { available: false };
-    }
-    catch {
-        return { available: false };
-    }
-}
-/**
- * Restore project source files from the S3 backup for `lua sync --pull`.
- *
- * Differs from `restoreProjectFromBackup` by byte-comparing before writing
- * (so the caller can report what actually changed) and by classifying the
- * restored files against `expectedPrimitives` to report backup coverage.
- */
-export async function restoreFromBackupForSync(apiKey, agentId, expectedPrimitives = [], projectPath, preFetchedManifest) {
-    const targetDir = projectPath || process.cwd();
-    try {
-        const backupApi = new BackupApi(BASE_URLS.API, apiKey, agentId);
-        const manifest = preFetchedManifest ?? (await backupApi.getBackupManifest()).data ?? null;
-        if (!manifest || !manifest.files?.length) {
-            return {
-                success: false,
-                filesWritten: 0,
-                filesUnchanged: 0,
-                primitivesResolved: [],
-                primitivesUnresolved: [...expectedPrimitives],
-                backupAgeDays: null,
-                error: 'No backup manifest found',
-            };
-        }
-        const uniqueHashes = [...new Set(manifest.files.map((f) => f.hash))];
-        const urlsResponse = await backupApi.getBlobUrls(uniqueHashes);
-        if (!urlsResponse.data) {
-            return {
-                success: false,
-                filesWritten: 0,
-                filesUnchanged: 0,
-                primitivesResolved: [],
-                primitivesUnresolved: [...expectedPrimitives],
-                backupAgeDays: computeBackupAgeDays(manifest),
-                error: 'Failed to get download URLs',
-            };
-        }
-        const blobs = await downloadBlobsParallel(urlsResponse.data.urls, 10);
-        const { filesWritten, filesUnchanged, restoredContents } = writeBackupFilesWithByteCompare(manifest, blobs, targetDir);
-        const { resolved, unresolved } = classifyPrimitiveCoverage(expectedPrimitives, restoredContents);
-        // After a successful restore, disk contents now match the server
-        // manifest we just pulled. Sync the local cache so subsequent
-        // `lua sync --pull` runs don't mis-read the freshly-restored files
-        // as "user edits since last push".
-        updateCacheFromServerManifest(manifest, targetDir);
-        return {
-            success: true,
-            filesWritten,
-            filesUnchanged,
-            primitivesResolved: resolved,
-            primitivesUnresolved: unresolved,
-            backupAgeDays: computeBackupAgeDays(manifest),
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        return {
-            success: false,
-            filesWritten: 0,
-            filesUnchanged: 0,
-            primitivesResolved: [],
-            primitivesUnresolved: [...expectedPrimitives],
-            backupAgeDays: null,
-            error: message,
-        };
-    }
-}
-/**
- * Write the local backup-manifest cache so it reflects the just-restored
- * server state. Used by `restoreFromBackupForSync` to keep the conflict
- * guard accurate on the next pull: without this, every file we just
- * restored would show up as "modified since last push" on the very next
- * `lua sync --pull` and trip the guard.
- *
- * Uses the server manifest's `createdAt` (when the backup was originally
- * pushed) rather than "now", so the cache records a timestamp consistent
- * with the state it's describing — not the moment we happened to pull it.
- */
-export function updateCacheFromServerManifest(manifest, projectPath = process.cwd()) {
-    writeBackupManifestCache({
-        lastHash: manifest.projectHash,
-        lastPushedAt: manifest.createdAt,
-        // See `pushBackup.ts` — external entries are sandboxed during restore
-        // so the conflict guard never inspects them; keeping them out of the
-        // cache keeps disk comparisons aligned with the files we actually
-        // write back to their original location.
-        files: manifest.files
-            .filter((f) => !f.external)
-            .map((f) => ({
-            relativePath: f.relativePath,
-            hash: f.hash,
-        })),
-    }, projectPath);
-}
-/**
- * Skip the write when disk bytes already match, so callers can distinguish
- * "9 files restored" from "9 files matched disk, 0 written."
- */
-function writeBackupFilesWithByteCompare(manifest, blobs, targetDir) {
-    let filesWritten = 0;
-    let filesUnchanged = 0;
-    const restoredContents = new Map();
-    for (const file of manifest.files) {
-        const content = blobs.get(file.hash);
-        if (!content) {
-            throw new Error(`Blob not found for hash: ${file.hash} (${file.relativePath})`);
-        }
-        // Namespace by `external` so in-project and external entries with
-        // the same relativePath (legitimately allowed by the M4 dedup fix)
-        // coexist in the Map instead of one silently clobbering the other.
-        // The consumer (classifyPrimitiveCoverage) is now aware of the
-        // prefix and strips it before its extension check.
-        restoredContents.set(makeRestoredContentsKey(file), content);
-        const filePath = resolveBackupFileTarget(file, targetDir);
-        if (fs.existsSync(filePath)) {
-            const existing = fs.readFileSync(filePath);
-            if (existing.equals(content)) {
-                filesUnchanged++;
-                continue;
-            }
-        }
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, content);
-        filesWritten++;
-    }
-    return { filesWritten, filesUnchanged, restoredContents };
-}
-/**
- * Prefix the `relativePath` with a namespace derived from `file.external`
- * so the restoredContents Map can hold both copies when a manifest has
- * two entries sharing the same relativePath (M4 permits this — one
- * in-project, one external/workspace-relative). Without the namespacing
- * the second write silently clobbers the first in the Map, which
- * breaks the design intent even though both files land correctly on
- * disk (resolveBackupFileTarget uses `file.external`, not the Map key).
- *
- * `ext:` and `loc:` are deliberately short and unlikely to appear at
- * the start of any real relativePath. Consumers MUST strip the prefix
- * before interpreting the key as a filesystem-relative path.
- */
-function makeRestoredContentsKey(file) {
-    return `${file.external ? 'ext:' : 'loc:'}${file.relativePath}`;
-}
-/**
- * Strip the `ext:` / `loc:` namespace prefix from a
- * restoredContents key, returning the raw relativePath. Safe to call
- * on unprefixed strings (returns them unchanged) for forward
- * compatibility with any older callers.
- */
-function stripRestoredContentsKey(key) {
-    if (key.startsWith('ext:'))
-        return key.slice(4);
-    if (key.startsWith('loc:'))
-        return key.slice(4);
-    return key;
-}
-/**
- * Fuzzy "does the backup define this primitive?" check: match the name as a
- * quoted string literal in any restored .ts/.tsx/.js/.jsx file. Avoids pulling
- * in a TS parser for sync reporting; can mis-classify when a name is built from
- * a variable or appears in a string literal that isn't a primitive declaration.
- */
-function classifyPrimitiveCoverage(expected, restoredContents) {
-    if (expected.length === 0) {
-        return { resolved: [], unresolved: [] };
-    }
-    const haystack = Array.from(restoredContents.entries())
-        // Strip the ext:/loc: namespace prefix the writer adds, then test
-        // the extension on the actual relativePath suffix. Without this,
-        // every prefixed key fails the regex and the haystack is empty.
-        .filter(([key]) => /\.(ts|tsx|js|jsx)$/.test(stripRestoredContentsKey(key)))
-        .map(([, buf]) => buf.toString('utf-8'))
-        .join('\n');
-    const resolved = [];
-    const unresolved = [];
-    for (const name of expected) {
-        const quoted = haystack.includes(`'${name}'`) || haystack.includes(`"${name}"`) || haystack.includes(`\`${name}\``);
-        if (quoted)
-            resolved.push(name);
-        else
-            unresolved.push(name);
-    }
-    return { resolved, unresolved };
-}
-function computeBackupAgeDays(manifest) {
-    const createdAt = manifest.createdAt;
-    if (!createdAt)
-        return null;
-    const created = new Date(createdAt).getTime();
-    if (!Number.isFinite(created))
-        return null;
-    const ageMs = Date.now() - created;
-    return Math.max(0, Math.floor(ageMs / (1000 * 60 * 60 * 24)));
-}
-//# sourceMappingURL=backup-helpers.js.map