@cleocode/core 2026.3.41 → 2026.3.43

package/dist/migration/agent-outputs.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Agent-outputs directory migration utility.
+ *
+ * Single source of truth for detecting, migrating, and cleaning up
+ * legacy agent-output directories. Handles the full lineage:
+ *
+ *   1. claudedocs/research-outputs/  (oldest, pre-v0.61.0)
+ *   2. claudedocs/agent-outputs/     (intermediate, pre-v0.70.0)
+ *   3. .cleo/agent-outputs/          (canonical, v0.80.0+)
+ *
+ * NOTE: The "research-outputs" naming predates the "agent-outputs" rename
+ * (T2348). Projects that still have research-outputs/ get their content
+ * merged into .cleo/agent-outputs/ in a single unified pass with
+ * MANIFEST.jsonl path rewriting and deduplication.
+ *
+ * Used by: upgrade.ts (cleo upgrade) and init.ts (cleo init).
+ *
+ * @task T4700
+ * @epic T4454
+ */
+/** Result of detecting legacy agent-output directories. */
+export interface LegacyDetectionResult {
+    /** Whether any legacy directories were found. */
+    hasLegacy: boolean;
+    /** claudedocs/research-outputs/ exists. */
+    hasResearchOutputs: boolean;
+    /** claudedocs/agent-outputs/ exists. */
+    hasLegacyAgentOutputs: boolean;
+    /** .cleo/agent-outputs/ already exists. */
+    hasCanonical: boolean;
+    /** Human-readable list of found legacy paths. */
+    legacyPaths: string[];
+}
+/** Result of running the agent-outputs migration. */
+export interface AgentOutputsMigrationResult {
+    /** Whether migration was performed. */
+    migrated: boolean;
+    /** Number of files copied to canonical location. */
+    filesCopied: number;
+    /** Number of manifest entries in the merged MANIFEST.jsonl. */
+    manifestEntries: number;
+    /** Legacy directories that were removed. */
+    removed: string[];
+    /** Human-readable summary of what happened. */
+    summary: string;
+}
+/**
+ * Detect legacy agent-output directories in a project.
+ *
+ * Read-only check — never modifies the filesystem.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param cleoDir - Absolute path to .cleo/ directory
+ */
+export declare function detectLegacyAgentOutputs(projectRoot: string, cleoDir: string): LegacyDetectionResult;
+/**
+ * Run the full agent-outputs migration.
+ *
+ * Copies files from all legacy locations into .cleo/agent-outputs/,
+ * merges MANIFEST.jsonl entries with path rewriting and deduplication,
+ * updates config.json, and removes legacy directories.
+ *
+ * Safe to call when no legacy directories exist (returns early).
+ * Safe to call when canonical directory already exists (merges).
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param cleoDir - Absolute path to .cleo/ directory
+ */
+export declare function migrateAgentOutputs(projectRoot: string, cleoDir: string): AgentOutputsMigrationResult;
+//# sourceMappingURL=agent-outputs.d.ts.map

package/dist/migration/agent-outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-outputs.d.ts","sourceRoot":"","sources":["../../src/migration/agent-outputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH,2DAA2D;AAC3D,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,wCAAwC;IACxC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,YAAY,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,qBAAqB,CAgBvB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,2BAA2B,CA2D7B"}

package/dist/migration/checksum.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Checksum utilities for backup verification.
+ *
+ * Provides SHA-256 checksum computation and backup verification
+ * to ensure data integrity during migrations.
+ *
+ * @task T4728
+ * @epic T4454
+ */
+/**
+ * Result of a backup verification operation.
+ */
+export interface VerificationResult {
+    /** Whether the backup is valid */
+    valid: boolean;
+    /** Error message if verification failed */
+    error?: string;
+    /** SHA-256 checksum of the source file */
+    sourceChecksum: string;
+    /** SHA-256 checksum of the backup file */
+    backupChecksum: string;
+}
+/**
+ * Compute SHA-256 checksum of a file.
+ *
+ * @param filePath - Path to the file
+ * @returns Hex-encoded SHA-256 checksum
+ * @task T4728
+ */
+export declare function computeChecksum(filePath: string): Promise<string>;
+/**
+ * Verify that a backup file matches the source file and is a valid SQLite database.
+ *
+ * Performs three checks:
+ * 1. Computes SHA-256 checksum of both files
+ * 2. Compares checksums to detect any content differences
+ * 3. Verifies the backup can be opened as a valid SQLite database
+ *
+ * @param sourcePath - Path to the source database file
+ * @param backupPath - Path to the backup file
+ * @returns VerificationResult with checksums and validity status
+ * @task T4728
+ */
+export declare function verifyBackup(sourcePath: string, backupPath: string): Promise<VerificationResult>;
+/**
+ * Quick checksum comparison without SQLite verification.
+ * Use when you only need to compare file contents.
+ *
+ * @param filePath1 - First file path
+ * @param filePath2 - Second file path
+ * @returns true if checksums match, false otherwise
+ * @task T4728
+ */
+export declare function compareChecksums(filePath1: string, filePath2: string): Promise<boolean>;
+//# sourceMappingURL=checksum.d.ts.map

package/dist/migration/checksum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/migration/checksum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAuC7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI7F"}

package/dist/migration/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Migration system - schema version detection and migration runner.
+ * @task T4468
+ * @epic T4454
+ */
+export type { AgentOutputsMigrationResult, LegacyDetectionResult, } from './agent-outputs.js';
+export { detectLegacyAgentOutputs, migrateAgentOutputs, } from './agent-outputs.js';
+export type { VerificationResult } from './checksum.js';
+export { compareChecksums, computeChecksum, verifyBackup, } from './checksum.js';
+export type { LogLevel, MigrationLogEntry, MigrationLoggerConfig, } from './logger.js';
+export { createMigrationLogger, getLatestMigrationLog, logFileExists, MigrationLogger, readMigrationLog, } from './logger.js';
+export type { PreflightResult } from './preflight.js';
+export { checkStorageMigration } from './preflight.js';
+export type { MigrationPhase, MigrationProgress, MigrationState, SourceFileInfo, } from './state.js';
+export { addMigrationError, addMigrationWarning, canResumeMigration, clearMigrationState, completeMigration, createMigrationState, failMigration, getMigrationSummary, isMigrationInProgress, loadMigrationState, updateMigrationPhase, updateMigrationProgress, updateMigrationState, verifySourceIntegrity, } from './state.js';
+export type { JsonFileValidation, JsonValidationResult, } from './validate.js';
+export { checkTaskCountMismatch, formatValidationResult, validateSourceFiles, } from './validate.js';
+/** Schema version info. */
+export interface SchemaVersion {
+    current: string;
+    target: string;
+    needsMigration: boolean;
+}
+/** Migration function signature. */
+export type MigrationFn = (data: unknown) => unknown;
+/** Migration definition. */
+export interface MigrationDef {
+    fromVersion: string;
+    toVersion: string;
+    description: string;
+    migrate: MigrationFn;
+}
+/** Migration run result. */
+export interface MigrationResult {
+    file: string;
+    fromVersion: string;
+    toVersion: string;
+    migrationsApplied: string[];
+    success: boolean;
+    errors: string[];
+    dryRun: boolean;
+}
+/** Status of all data files. */
+export interface MigrationStatus {
+    todoJson: SchemaVersion | null;
+    configJson: SchemaVersion | null;
+    archiveJson: SchemaVersion | null;
+}
+/**
+ * Detect schema version from a data file.
+ * @task T4468
+ */
+export declare function detectVersion(data: unknown): string;
+/**
+ * Compare two version strings (X.Y.Z format, works for both semver and CalVer).
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ * @task T4468
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Get migration status for all data files.
+ * @task T4468
+ */
+export declare function getMigrationStatus(cwd?: string): Promise<MigrationStatus>;
+/**
+ * Run migrations on a data file.
+ * @task T4468
+ */
+export declare function runMigration(fileType: string, options?: {
+    dryRun?: boolean;
+}, cwd?: string): Promise<MigrationResult>;
+/**
+ * Run all pending migrations.
+ * @task T4468
+ */
+export declare function runAllMigrations(options?: {
+    dryRun?: boolean;
+}, cwd?: string): Promise<MigrationResult[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/migration/index.d.ts.map

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

package/dist/migration/logger.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Structured logging for migration operations.
+ *
+ * Provides audit trail and debugging support for all migration phases.
+ * Logs are written in JSONL format for easy parsing and appending.
+ *
+ * @task T4727
+ * @epic T4454
+ */
+/** Log entry severity level */
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+/** Single migration log entry */
+export interface MigrationLogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Migration phase (init, backup, import, verify, complete, etc.) */
+    phase: string;
+    /** Specific operation within phase */
+    operation: string;
+    /** Human-readable message */
+    message: string;
+    /** Duration since migration start in milliseconds */
+    durationMs: number;
+    /** Additional structured data */
+    data?: Record<string, unknown>;
+}
+/** Migration logger configuration */
+export interface MigrationLoggerConfig {
+    /** Maximum number of log files to retain */
+    maxLogFiles?: number;
+    /** Minimum log level to record */
+    minLevel?: LogLevel;
+    /** Enable console output in addition to file logging */
+    consoleOutput?: boolean;
+}
+/** Structured logger for migration operations */
+export declare class MigrationLogger {
+    private logPath;
+    private entries;
+    private startTime;
+    private cleoDir;
+    private config;
+    /**
+     * Create a new migration logger.
+     * @param cleoDir - Path to .cleo directory
+     * @param config - Optional configuration
+     */
+    constructor(cleoDir: string, config?: MigrationLoggerConfig);
+    /**
+     * Get numeric priority for log level comparison.
+     */
+    private getLevelPriority;
+    /**
+     * Check if a log level should be recorded.
+     */
+    private shouldLog;
+    /**
+     * Write a log entry.
+     */
+    private log;
+    /**
+     * Log an info-level message.
+     */
+    info(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log a warning-level message.
+     */
+    warn(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log an error-level message.
+     */
+    error(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log a debug-level message.
+     */
+    debug(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log file operation with size information.
+     */
+    logFileOperation(phase: string, operation: 'read' | 'write' | 'backup' | 'rename' | 'delete', sourcePath: string, targetPath?: string, additionalData?: Record<string, unknown>): void;
+    /**
+     * Log validation result.
+     */
+    logValidation(phase: string, target: string, valid: boolean, details?: Record<string, unknown>, errors?: string[]): void;
+    /**
+     * Log import progress.
+     */
+    logImportProgress(phase: string, entityType: string, imported: number, total: number, additionalData?: Record<string, unknown>): void;
+    /**
+     * Log phase start.
+     */
+    phaseStart(phase: string, data?: Record<string, unknown>): void;
+    /**
+     * Log phase completion.
+     */
+    phaseComplete(phase: string, data?: Record<string, unknown>): void;
+    /**
+     * Log phase failure.
+     */
+    phaseFailed(phase: string, error: Error | string, data?: Record<string, unknown>): void;
+    /**
+     * Clean up old log files, keeping only the most recent ones.
+     */
+    private cleanupOldLogs;
+    /**
+     * Get the absolute path to the log file.
+     */
+    getLogPath(): string;
+    /**
+     * Get the path to the log file relative to cleoDir.
+     */
+    getRelativeLogPath(): string;
+    /**
+     * Get all logged entries.
+     */
+    getEntries(): MigrationLogEntry[];
+    /**
+     * Get entries filtered by level.
+     */
+    getEntriesByLevel(level: LogLevel): MigrationLogEntry[];
+    /**
+     * Get entries for a specific phase.
+     */
+    getEntriesByPhase(phase: string): MigrationLogEntry[];
+    /**
+     * Get the total duration of the migration so far.
+     */
+    getDurationMs(): number;
+    /**
+     * Get summary statistics for the migration.
+     */
+    getSummary(): {
+        totalEntries: number;
+        durationMs: number;
+        errors: number;
+        warnings: number;
+        info: number;
+        debug: number;
+        phases: string[];
+    };
+}
+/**
+ * Create a migration logger for the given cleo directory.
+ * Convenience function for functional programming style.
+ */
+export declare function createMigrationLogger(cleoDir: string, config?: MigrationLoggerConfig): MigrationLogger;
+/**
+ * Read and parse a migration log file.
+ */
+export declare function readMigrationLog(logPath: string): MigrationLogEntry[];
+/**
+ * Check if a log file exists and is readable.
+ */
+export declare function logFileExists(logPath: string): boolean;
+/**
+ * Get the most recent migration log file for a cleo directory.
+ */
+export declare function getLatestMigrationLog(cleoDir: string): string | null;
+//# sourceMappingURL=logger.d.ts.map

package/dist/migration/logger.d.ts.map

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

package/dist/migration/preflight.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Backward-compatible pre-flight migration exports.
+ *
+ * Runtime callers should import from src/core/system/storage-preflight.ts.
+ *
+ * @task T5305
+ */
+export type { PreflightResult } from '../system/storage-preflight.js';
+export { checkStorageMigration } from '../system/storage-preflight.js';
+//# sourceMappingURL=preflight.d.ts.map

package/dist/migration/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/migration/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/migration/state.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Migration state tracking and recovery.
+ *
+ * Provides persistent tracking of migration progress to enable:
+ * - Resumable migrations after interruptions
+ * - Debugging of failed migrations
+ * - Progress monitoring during long operations
+ *
+ * @task T4726
+ * @epic T4454
+ */
+/** Migration phase - tracks current step in the migration process */
+export type MigrationPhase = 'init' | 'backup' | 'validate' | 'import' | 'verify' | 'cleanup' | 'complete' | 'failed';
+/** Source file info with checksum for integrity verification */
+export interface SourceFileInfo {
+    path: string;
+    checksum: string;
+    taskCount?: number;
+    sessionCount?: number;
+    archivedCount?: number;
+}
+/** Migration progress tracking */
+export interface MigrationProgress {
+    tasksImported: number;
+    archivedImported: number;
+    sessionsImported: number;
+    totalTasks: number;
+    totalArchived: number;
+    totalSessions: number;
+}
+/** Complete migration state structure */
+export interface MigrationState {
+    version: '1.0.0';
+    startedAt: string;
+    phase: MigrationPhase;
+    sourceFiles: {
+        todoJson?: SourceFileInfo;
+        sessionsJson?: SourceFileInfo;
+        archiveJson?: SourceFileInfo;
+    };
+    backupPath?: string;
+    tempPath?: string;
+    progress: MigrationProgress;
+    errors: string[];
+    warnings: string[];
+    completedAt?: string;
+}
+/**
+ * Create initial migration state at the start of migration.
+ *
+ * Captures source file checksums and initializes progress tracking.
+ * Uses atomic write pattern to ensure state is never in an inconsistent state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param sourceFiles - Optional pre-computed source file info
+ * @returns The created migration state
+ * @task T4726
+ */
+export declare function createMigrationState(cleoDir: string, sourceFiles?: MigrationState['sourceFiles']): Promise<MigrationState>;
+/**
+ * Update migration state with partial updates.
+ *
+ * Merges updates with existing state and writes atomically.
+ * Automatically adds timestamp to phase transitions.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param updates - Partial state updates to apply
+ * @returns The updated migration state
+ * @task T4726
+ */
+export declare function updateMigrationState(cleoDir: string, updates: Partial<MigrationState>): Promise<MigrationState>;
+/**
+ * Update just the migration phase.
+ * Convenience wrapper for common phase transition.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param phase - New phase
+ * @returns The updated migration state
+ * @task T4726
+ */
+export declare function updateMigrationPhase(cleoDir: string, phase: MigrationPhase): Promise<MigrationState>;
+/**
+ * Update progress counters during import.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param progress - Progress updates (only changed counters needed)
+ * @returns The updated migration state
+ * @task T4726
+ */
+export declare function updateMigrationProgress(cleoDir: string, progress: Partial<MigrationProgress>): Promise<MigrationState>;
+/**
+ * Add an error to the migration state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param error - Error message
+ * @returns The updated migration state
+ * @task T4726
+ */
+export declare function addMigrationError(cleoDir: string, error: string): Promise<MigrationState>;
+/**
+ * Add a warning to the migration state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param warning - Warning message
+ * @returns The updated migration state
+ * @task T4726
+ */
+export declare function addMigrationWarning(cleoDir: string, warning: string): Promise<MigrationState>;
+/**
+ * Load existing migration state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Migration state, or null if no state file exists
+ * @task T4726
+ */
+export declare function loadMigrationState(cleoDir: string): Promise<MigrationState | null>;
+/**
+ * Check if a migration is in progress.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns true if migration state exists and is not complete/failed
+ * @task T4726
+ */
+export declare function isMigrationInProgress(cleoDir: string): Promise<boolean>;
+/**
+ * Check if migration can be resumed.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Object with resume info, or null if cannot resume
+ * @task T4726
+ */
+export declare function canResumeMigration(cleoDir: string): Promise<{
+    canResume: boolean;
+    phase: MigrationPhase;
+    progress: MigrationProgress;
+    errors: string[];
+} | null>;
+/**
+ * Mark migration as complete.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns The completed migration state
+ * @task T4726
+ */
+export declare function completeMigration(cleoDir: string): Promise<MigrationState>;
+/**
+ * Mark migration as failed with error details.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param error - Primary error message
+ * @returns The failed migration state
+ * @task T4726
+ */
+export declare function failMigration(cleoDir: string, error: string): Promise<MigrationState>;
+/**
+ * Clear migration state file.
+ * Safe to call even if state doesn't exist.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @task T4726
+ */
+export declare function clearMigrationState(cleoDir: string): Promise<void>;
+/**
+ * Get a summary of migration state for display.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Human-readable summary, or null if no state
+ * @task T4726
+ */
+export declare function getMigrationSummary(cleoDir: string): Promise<string | null>;
+/**
+ * Verify source files haven't changed since migration started.
+ *
+ * Compares current checksums with stored checksums to detect
+ * if source files were modified during migration.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Object with verification results
+ * @task T4726
+ */
+export declare function verifySourceIntegrity(cleoDir: string): Promise<{
+    valid: boolean;
+    changed: string[];
+    missing: string[];
+}>;
+//# sourceMappingURL=state.d.ts.map

package/dist/migration/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/migration/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,qEAAqE;AACrE,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE;QACX,QAAQ,CAAC,EAAE,cAAc,CAAC;QAC1B,YAAY,CAAC,EAAE,cAAc,CAAC;QAC9B,WAAW,CAAC,EAAE,cAAc,CAAC;KAC9B,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmCD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,GAC1C,OAAO,CAAC,cAAc,CAAC,CA0DzB;AAwBD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,OAAO,CAAC,cAAc,CAAC,CA0CzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,CAAC,CAEzB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,OAAO,CAAC,cAAc,CAAC,CAgBzB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAU/F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CASzB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQxF;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI7E;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACjE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,IAAI,CAAC,CAaR;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAehF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAK3F;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxE;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoCjF;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACpE,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC,CA4BD"}

package/dist/migration/validate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pre-migration JSON validation.
+ *
+ * Validates all JSON source files BEFORE any destructive database operations.
+ * This prevents data loss scenarios where the database is deleted but JSON parsing fails.
+ *
+ * @task T4725
+ * @epic T4454
+ */
+/** Result of validating a single JSON file. */
+export interface JsonFileValidation {
+    valid: boolean;
+    exists: boolean;
+    count: number;
+    error?: string;
+    line?: number;
+    column?: number;
+}
+/** Complete validation result for all source files. */
+export interface JsonValidationResult {
+    valid: boolean;
+    todoJson: JsonFileValidation;
+    sessionsJson: JsonFileValidation;
+    archiveJson: JsonFileValidation;
+    totalTasks: number;
+    warnings: string[];
+}
+/**
+ * Validate all JSON source files before migration.
+ *
+ * This function MUST be called BEFORE any destructive database operations.
+ * It checks that all JSON files are parseable and contain expected data.
+ *
+ * @param cleoDir - Path to the .cleo directory
+ * @returns Validation result with details for each file
+ * @task T4725
+ */
+export declare function validateSourceFiles(cleoDir: string): JsonValidationResult;
+/**
+ * Format validation result for human-readable output.
+ *
+ * @param result - Validation result
+ * @returns Formatted string
+ */
+export declare function formatValidationResult(result: JsonValidationResult): string;
+/**
+ * Check for task count mismatch between existing database and JSON.
+ *
+ * This helps detect cases where the database has data but JSON is empty
+ * (indicating a potential configuration or path issue).
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param jsonTaskCount - Number of tasks found in JSON
+ * @returns Warning message if mismatch detected, null otherwise
+ */
+export declare function checkTaskCountMismatch(cleoDir: string, jsonTaskCount: number): string | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/migration/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/migration/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,YAAY,EAAE,kBAAkB,CAAC;IACjC,WAAW,EAAE,kBAAkB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,CA2EzE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAwD3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0B5F"}