lua-cli 3.15.2 → 3.16.0

package/dist/utils/backup-helpers.d.ts

@@ -1,290 +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 type { CompilationManifest, ProjectFile } from '../compiler/types.js';
-import type { BackupFileRef, BackupManifest } from '../interfaces/backup.js';
-import type { YamlConfigBackup } from '../types/yaml.types.js';
-export interface CachedBackupManifest {
-    lastHash: string;
-    lastPushedAt: string;
-    files: Array<{
-        relativePath: string;
-        hash: string;
-    }>;
-}
-/**
- * Calculate a hash for a string content.
- *
- * @param content - The content to hash
- * @returns SHA-256 hash as hex string
- */
-export declare function hashContent(content: string): string;
-/**
- * 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 declare function calculateProjectHash(projectFiles: ProjectFile[]): string;
-/**
- * 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 declare function getCurrentProjectHash(projectPath?: string): string | null;
-/**
- * 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 declare function loadProjectSources(manifest: CompilationManifest, projectPath?: string): Map<string, string>;
-/**
- * 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 declare function loadSourceByHash(hash: string, relativePath: string, projectPath?: string): string | null;
-/**
- * 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 declare function prepareFileRefs(projectPath?: string): BackupFileRef[];
-/**
- * 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 declare function reconcileManifestWithDisk(projectPath?: string): void;
-/**
- * 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 declare function uploadBlobsToS3(uploadUrls: Record<string, string>, manifest: CompilationManifest, projectPath?: string, onProgress?: (uploaded: number, total: number) => void, concurrency?: number): Promise<number>;
-/**
- * Get all unique hashes from the manifest.
- *
- * @param projectPath - Path to the project root
- * @returns Array of unique content hashes
- */
-export declare function getAllFileHashes(projectPath?: string): string[];
-/**
- * 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 declare function downloadBlobsParallel(urls: Record<string, string>, concurrency?: number): Promise<Map<string, Buffer>>;
-/**
- * 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 declare function restoreProjectFromBackup(manifest: BackupManifest, blobs: Map<string, Buffer>, targetDir: string, options?: {
-    overwrite?: boolean;
-}): void;
-/**
- * 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 declare function resolveBackupFileTarget(file: BackupFileRef, targetDir: string): string;
-/**
- * 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 declare function checkRestoreConflicts(manifest: BackupManifest, targetDir: string): {
-    newFiles: string[];
-    existingFiles: string[];
-    totalFiles: number;
-};
-/**
- * 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 declare function isBackupOutOfSync(currentHash: string, tracking: YamlConfigBackup | undefined): boolean;
-/**
- * Create backup tracking object after successful push.
- *
- * @param projectHash - The hash of the pushed backup
- * @returns YamlConfigBackup object for storing in YAML
- */
-export declare function createBackupTracking(projectHash: string): YamlConfigBackup;
-export declare function getBackupCachePath(projectPath?: string): string;
-export declare function writeBackupManifestCache(cache: CachedBackupManifest, projectPath?: string): void;
-export declare function readBackupManifestCache(projectPath?: string): CachedBackupManifest | null;
-export type ConflictGuardWarning = 'no-tracking' | 'manifest-unavailable';
-export interface ConflictGuardResult {
-    conflicts: string[];
-    warning: ConflictGuardWarning | null;
-}
-export declare function detectLocalConflictsForPull(incomingFiles: Array<{
-    relativePath: string;
-    hash: string;
-    external?: boolean;
-}>, projectPath?: string): ConflictGuardResult;
-export declare function fetchBackupManifestForPull(apiKey: string, agentId: string): Promise<{
-    fetched: BackupManifest | null;
-}>;
-/**
- * Result of comparing the server's backup freshness against this machine's
- * local `lua push backup` tracking cache. Callers (currently
- * `pushBackupCommand`) use this to refuse a push that would silently
- * clobber a newer server-side backup from another machine.
- *
- * We surface the project HASHES (not timestamps) because the server's
- * backup `createdAt` is the original record creation time — frequently
- * weeks or months stale even for a just-pushed backup. Showing that
- * alongside a "server is newer" message contradicts itself. Hashes are
- * what actually drive the decision, and they're unambiguous.
- */
-export interface ServerBackupFreshness {
-    /** True when the server's current backup hash differs from this machine's last-pushed hash. */
-    serverNewer: boolean;
-    /** Server's current backup projectHash (when known). */
-    serverProjectHash?: string;
-    /** This machine's last-pushed projectHash (when known). */
-    localLastHash?: string;
-    /** True when we were unable to reach the server's backup metadata endpoint. */
-    checkFailed?: boolean;
-}
-/**
- * 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 declare function decideBackupFreshness(local: CachedBackupManifest | null, serverMetadata: {
-    projectHash: string;
-} | null): ServerBackupFreshness;
-/**
- * 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 declare function checkServerBackupNewerThanLocal(apiKey: string, agentId: string, projectPath?: string): Promise<ServerBackupFreshness>;
-/**
- * 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 declare function checkBackupAvailability(apiKey: string, agentId: string): Promise<{
-    available: boolean;
-    fileCount?: number;
-    lastPushedAt?: string;
-}>;
-/**
- * Result of a sync-driven backup restore. `filesWritten`/`filesUnchanged`
- * reflect actual disk activity (byte-level compare), and the primitive lists
- * tell the caller which drifted primitives the backup could resolve.
- */
-export interface RestoreForSyncResult {
-    success: boolean;
-    filesWritten: number;
-    filesUnchanged: number;
-    primitivesResolved: string[];
-    primitivesUnresolved: string[];
-    backupAgeDays: number | null;
-    error?: string;
-}
-/**
- * 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 declare function restoreFromBackupForSync(apiKey: string, agentId: string, expectedPrimitives?: string[], projectPath?: string, preFetchedManifest?: BackupManifest | null): Promise<RestoreForSyncResult>;
-/**
- * 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 declare function updateCacheFromServerManifest(manifest: BackupManifest, projectPath?: string): void;
-//# sourceMappingURL=backup-helpers.d.ts.map

package/dist/utils/backup-helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"backup-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/backup-helpers.ts"],"names":[],"mappings":"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"}