qraft/dist/core/manifestManager.d.ts

A powerful CLI tool to qraft structured project setups from GitHub template repositories

import { BoxManifest } from '../types';
/**
 * Custom error types for manifest operations
 */
export declare class ManifestError extends Error {
    readonly code: string;
    readonly cause?: Error | undefined;
    constructor(message: string, code: string, cause?: Error | undefined);
}
export declare class ManifestCorruptionError extends ManifestError {
    constructor(message: string, cause?: Error);
}
export declare class ManifestNotFoundError extends ManifestError {
    constructor(message: string, cause?: Error);
}
export declare class ManifestValidationError extends ManifestError {
    constructor(message: string, cause?: Error);
}
export declare class ManifestPermissionError extends ManifestError {
    constructor(message: string, cause?: Error);
}
/**
 * Sync state enumeration
 */
export type SyncState = 'synced' | 'local_newer' | 'remote_newer' | 'diverged' | 'unknown';
/**
 * Metadata stored alongside local manifests for sync state management
 */
export interface ManifestMetadata {
    /** Timestamp when manifest was last synced */
    lastSyncTimestamp: number;
    /** Timestamp when manifest was first created locally */
    createdTimestamp: number;
    /** Timestamp when manifest was last modified locally */
    lastModifiedTimestamp: number;
    /** Checksum of the manifest content for integrity verification */
    checksum: string;
    /** Source registry where manifest was downloaded from */
    sourceRegistry?: string;
    /** Source box reference */
    sourceBoxReference?: string;
    /** Version of the manifest when last synced */
    lastSyncedVersion?: string;
    /** Current sync state */
    syncState: SyncState;
    /** Number of sync operations performed */
    syncCount: number;
    /** Last known remote checksum (if available) */
    lastRemoteChecksum?: string;
    /** Metadata format version for future compatibility */
    metadataVersion: string;
}
/**
 * Local manifest entry combining manifest and metadata
 */
export interface LocalManifestEntry {
    manifest: BoxManifest;
    metadata: ManifestMetadata;
}
/**
 * Sync statistics for a local manifest
 */
export interface SyncStats {
    /** Current sync state */
    syncState: SyncState;
    /** Number of sync operations performed */
    syncCount: number;
    /** Days since last sync */
    daysSinceLastSync: number;
    /** Days since manifest was created */
    daysSinceCreated: number;
    /** Timestamp of last sync */
    lastSyncTimestamp: number;
    /** Timestamp when manifest was created */
    createdTimestamp: number;
    /** Whether we have a remote checksum for comparison */
    hasRemoteChecksum: boolean;
}
/**
 * Result of manifest recovery operation
 */
export interface ManifestRecoveryResult {
    /** Whether recovery was successful */
    success: boolean;
    /** Method used for recovery */
    method: 'none' | 'backup_restore' | 'auto_backup_restore' | 'reconstruction';
    /** Errors encountered during recovery */
    errors: string[];
    /** Warnings about the recovery process */
    warnings: string[];
}
/**
 * Result of manifest integrity validation
 */
export interface ManifestIntegrityResult {
    /** Whether the manifest is valid */
    isValid: boolean;
    /** Critical issues found */
    issues: string[];
    /** Non-critical warnings */
    warnings: string[];
    /** Whether the manifest can potentially be recovered */
    canRecover: boolean;
}
/**
 * Result of manifest comparison operation
 */
export interface ManifestComparisonResult {
    /** Whether manifests are identical */
    isIdentical: boolean;
    /** Fields that differ between manifests */
    differences: ManifestFieldDifference[];
    /** Overall change severity */
    severity: 'none' | 'low' | 'medium' | 'high' | 'critical';
}
/**
 * Individual field difference in manifest comparison
 */
export interface ManifestFieldDifference {
    field: keyof BoxManifest;
    oldValue: any;
    newValue: any;
    changeType: 'added' | 'removed' | 'modified';
    impact: 'low' | 'medium' | 'high' | 'critical';
}
/**
 * ManifestManager handles local manifest storage, retrieval, and comparison operations
 */
export declare class ManifestManager {
    /**
     * Store a manifest locally in the target directory
     * @param targetDirectory Directory where the box is being stored
     * @param manifest Box manifest to store
     * @param sourceRegistry Optional source registry
     * @param sourceBoxReference Optional source box reference
     * @returns Promise<void>
     */
    storeLocalManifest(targetDirectory: string, manifest: BoxManifest, sourceRegistry?: string, sourceBoxReference?: string, isUpdate?: boolean): Promise<void>;
    /**
     * Retrieve local manifest from target directory
     * @param targetDirectory Directory to search for local manifest
     * @returns Promise<LocalManifestEntry | null> Local manifest entry or null if not found
     */
    getLocalManifest(targetDirectory: string): Promise<LocalManifestEntry | null>;
    /**
     * Compare two manifests and return detailed comparison result
     * @param localManifest Local manifest (can be null if no local manifest exists)
     * @param remoteManifest Remote manifest
     * @returns ManifestComparisonResult Detailed comparison result
     */
    compareManifests(localManifest: BoxManifest | null, remoteManifest: BoxManifest): ManifestComparisonResult;
    /**
     * Check if a local manifest exists in the target directory
     * @param targetDirectory Directory to check
     * @returns Promise<boolean> True if local manifest exists
     */
    hasLocalManifest(targetDirectory: string): Promise<boolean>;
    /**
     * Remove local manifest from target directory
     * @param targetDirectory Directory to remove manifest from
     * @returns Promise<void>
     */
    removeLocalManifest(targetDirectory: string): Promise<void>;
    /**
     * Update sync state for a local manifest
     * @param targetDirectory Directory containing the manifest
     * @param newState New sync state
     * @param remoteChecksum Optional remote checksum for comparison
     * @returns Promise<void>
     */
    updateSyncState(targetDirectory: string, newState: SyncState, remoteChecksum?: string): Promise<void>;
    /**
     * Determine sync state by comparing local and remote manifests
     * @param localManifest Local manifest entry
     * @param remoteManifest Remote manifest
     * @returns SyncState Current sync state
     */
    determineSyncState(localManifest: LocalManifestEntry | null, remoteManifest: BoxManifest): SyncState;
    /**
     * Get sync statistics for a local manifest
     * @param targetDirectory Directory containing the manifest
     * @returns Promise<SyncStats | null> Sync statistics or null if no manifest
     */
    getSyncStats(targetDirectory: string): Promise<SyncStats | null>;
    /**
     * Update metadata when manifest is modified locally
     * @param targetDirectory Directory containing the manifest
     * @param updatedManifest Updated manifest
     * @returns Promise<void>
     */
    updateLocalManifest(targetDirectory: string, updatedManifest: BoxManifest): Promise<void>;
    /**
     * Check if local manifest needs sync based on metadata
     * @param targetDirectory Directory containing the manifest
     * @param maxDaysWithoutSync Maximum days without sync before flagging
     * @returns Promise<boolean> True if sync is needed
     */
    needsSync(targetDirectory: string, maxDaysWithoutSync?: number): Promise<boolean>;
    /**
     * Attempt to recover from corrupted manifest files
     * @param targetDirectory Directory with corrupted manifest
     * @param backupDirectory Optional backup directory to restore from
     * @returns Promise<ManifestRecoveryResult> Recovery result
     */
    recoverCorruptedManifest(targetDirectory: string, backupDirectory?: string): Promise<ManifestRecoveryResult>;
    /**
     * Attempt to reconstruct a manifest from available information
     * @param targetDirectory Directory to analyze
     * @returns Promise<BoxManifest | null> Reconstructed manifest or null if not possible
     */
    private reconstructManifest;
    /**
     * Validate manifest integrity and report issues
     * @param targetDirectory Directory to validate
     * @returns Promise<ManifestIntegrityResult> Integrity check result
     */
    validateManifestIntegrity(targetDirectory: string): Promise<ManifestIntegrityResult>;
    /**
     * Calculate checksum for manifest content
     * @param manifest Box manifest
     * @returns string SHA-256 checksum
     */
    private calculateChecksum;
    /**
     * Compare a single field between manifests
     */
    private compareField;
    /**
     * Compare array fields between manifests
     */
    private compareArrayField;
    /**
     * Get impact level for a specific manifest field
     */
    private getFieldImpact;
    /**
     * Calculate overall severity from differences
     */
    private calculateSeverity;
    /**
     * Generate differences for a completely new manifest
     */
    private getNewManifestDifferences;
}
//# sourceMappingURL=manifestManager.d.ts.map