@cleocode/core 2026.3.42 → 2026.3.44

package/dist/store/json.d.ts

@@ -0,0 +1,57 @@
+/**
+ * JSON read/write with schema validation, locking, and backup.
+ * This is the primary data access layer for CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+/**
+ * Read and parse a JSON file.
+ * Returns null if the file does not exist.
+ */
+export declare function readJson<T = unknown>(filePath: string): Promise<T | null>;
+/**
+ * Read a JSON file, throwing if it doesn't exist.
+ */
+export declare function readJsonRequired<T = unknown>(filePath: string): Promise<T>;
+/**
+ * Compute a truncated SHA-256 checksum of a value.
+ * Used for integrity verification (matches Bash CLI's 16-char hex format).
+ */
+export declare function computeChecksum(data: unknown): string;
+/** Options for saveJson. */
+export interface SaveJsonOptions {
+    /** Directory for backups. If omitted, no backup is created. */
+    backupDir?: string;
+    /** Maximum number of backups to retain. Default: 5. */
+    maxBackups?: number;
+    /** JSON indentation. Default: 2. */
+    indent?: number;
+    /** Validation function. Called before write; throw to abort. */
+    validate?: (data: unknown) => void | Promise<void>;
+}
+/**
+ * Save JSON data with optional locking, backup, and validation.
+ * Follows the CLEO atomic write pattern:
+ *   1. Acquire lock
+ *   2. Validate data
+ *   3. Create backup of existing file
+ *   4. Atomic write (temp file -> rename)
+ *   5. Release lock
+ */
+export declare function saveJson(filePath: string, data: unknown, options?: SaveJsonOptions): Promise<void>;
+/**
+ * Append a line to a JSONL file atomically.
+ * Used for manifest entries and audit logs.
+ */
+export declare function appendJsonl(filePath: string, entry: unknown): Promise<void>;
+/**
+ * Read log entries from a hybrid JSON/JSONL file.
+ * Handles three formats:
+ *   1. Pure JSON: `{ "entries": [...] }` (legacy bash format)
+ *   2. Pure JSONL: one JSON object per line (new TS format)
+ *   3. Hybrid: JSON object followed by JSONL lines (migration state)
+ * Returns a flat array of all entries found.
+ * @task T4622
+ */
+export declare function readLogEntries(filePath: string): Promise<Record<string, unknown>[]>;
+//# sourceMappingURL=json.d.ts.map

package/dist/store/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/store/json.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAS/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAwCf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjF;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CA8FzF"}

package/dist/store/lifecycle-store.d.ts

@@ -0,0 +1,125 @@
+/**
+ * SQLite-backed lifecycle store operations.
+ *
+ * Query and mutation functions for lifecycle pipeline tables:
+ * lifecycle_pipelines, lifecycle_stages, lifecycle_gate_results,
+ * lifecycle_evidence, lifecycle_transitions.
+ *
+ * Used by src/core/lifecycle/resume.ts to avoid direct store-layer imports.
+ *
+ * @task T4832
+ * @epic T4454
+ */
+import * as schema from './tasks-schema.js';
+/** Row shape for pipeline + stage + task JOIN. */
+export interface PipelineStageTaskRow {
+    pipeline: typeof schema.lifecyclePipelines.$inferSelect;
+    stage: typeof schema.lifecycleStages.$inferSelect;
+    task: typeof schema.tasks.$inferSelect;
+}
+/** Row shape for pipeline + stage JOIN. */
+export interface PipelineStageRow {
+    pipeline: typeof schema.lifecyclePipelines.$inferSelect;
+    stageRecord: typeof schema.lifecycleStages.$inferSelect;
+}
+/**
+ * Find active pipelines joined with their stages and tasks.
+ * Optionally filters by specific task IDs.
+ *
+ * @param taskIds - Optional list of task IDs to filter by
+ * @param cwd - Working directory for database
+ * @returns Rows with pipeline, stage, and task data
+ */
+export declare function findActivePipelinesWithStagesAndTasks(taskIds?: string[], cwd?: string): Promise<PipelineStageTaskRow[]>;
+/**
+ * Find a pipeline with its current stage and task by taskId.
+ * Matches stages where stageName equals the pipeline's currentStageId.
+ *
+ * @param taskId - Task ID to look up
+ * @param cwd - Working directory for database
+ * @returns Matching rows (typically 0 or 1)
+ */
+export declare function findPipelineWithCurrentStageAndTask(taskId: string, cwd?: string): Promise<PipelineStageTaskRow[]>;
+/**
+ * Find a pipeline and a specific stage by taskId and stageName.
+ *
+ * @param taskId - Task ID
+ * @param stageName - Stage name to match
+ * @param cwd - Working directory for database
+ * @returns Matching rows (typically 0 or 1)
+ */
+export declare function findPipelineWithStage(taskId: string, stageName: string, cwd?: string): Promise<PipelineStageRow[]>;
+/**
+ * Update pipeline's currentStageId.
+ *
+ * @param pipelineId - Pipeline ID to update
+ * @param currentStageId - New current stage identifier
+ * @param cwd - Working directory for database
+ */
+export declare function updatePipelineCurrentStage(pipelineId: string, currentStageId: string, cwd?: string): Promise<void>;
+/**
+ * Get all stages for a pipeline, ordered by sequence.
+ *
+ * @param pipelineId - Pipeline ID
+ * @param cwd - Working directory for database
+ * @returns All stage rows for the pipeline
+ */
+export declare function getStagesByPipelineId(pipelineId: string, cwd?: string): Promise<(typeof schema.lifecycleStages.$inferSelect)[]>;
+/**
+ * Update a stage's status to 'in_progress' and clear block fields.
+ *
+ * @param stageId - Stage ID to update
+ * @param startedAt - ISO timestamp for when the stage started
+ * @param cwd - Working directory for database
+ */
+export declare function activateStage(stageId: string, startedAt: string, cwd?: string): Promise<void>;
+/**
+ * Find pipeline with current stage (no task join) by taskId.
+ * Used by checkBlockedStageDetails.
+ *
+ * @param taskId - Task ID
+ * @param cwd - Working directory for database
+ * @returns Matching rows
+ */
+export declare function findPipelineWithCurrentStage(taskId: string, cwd?: string): Promise<PipelineStageRow[]>;
+/**
+ * Get gate results for a stage, ordered by checkedAt descending.
+ *
+ * @param stageId - Stage ID
+ * @param cwd - Working directory for database
+ * @returns Gate result rows
+ */
+export declare function getGateResultsByStageId(stageId: string, cwd?: string): Promise<(typeof schema.lifecycleGateResults.$inferSelect)[]>;
+/**
+ * Get gate results for a stage without ordering (for simple checks).
+ *
+ * @param stageId - Stage ID
+ * @param cwd - Working directory for database
+ * @returns Gate result rows
+ */
+export declare function getGateResultsByStageIdUnordered(stageId: string, cwd?: string): Promise<(typeof schema.lifecycleGateResults.$inferSelect)[]>;
+/**
+ * Get evidence for a stage, ordered by recordedAt descending.
+ *
+ * @param stageId - Stage ID
+ * @param cwd - Working directory for database
+ * @returns Evidence rows
+ */
+export declare function getEvidenceByStageId(stageId: string, cwd?: string): Promise<(typeof schema.lifecycleEvidence.$inferSelect)[]>;
+/**
+ * Get recent transitions for a pipeline, ordered by createdAt descending.
+ *
+ * @param pipelineId - Pipeline ID
+ * @param limit - Max rows to return (default: 10)
+ * @param cwd - Working directory for database
+ * @returns Transition rows
+ */
+export declare function getRecentTransitions(pipelineId: string, limit?: number, cwd?: string): Promise<(typeof schema.lifecycleTransitions.$inferSelect)[]>;
+/**
+ * Insert a new transition record.
+ *
+ * @param transition - Transition data to insert
+ * @param cwd - Working directory for database
+ */
+export declare function insertTransition(transition: typeof schema.lifecycleTransitions.$inferInsert, cwd?: string): Promise<void>;
+//# sourceMappingURL=lifecycle-store.d.ts.map

package/dist/store/lifecycle-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-store.d.ts","sourceRoot":"","sources":["../../src/store/lifecycle-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAM5C,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC;IACxD,KAAK,EAAE,OAAO,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC;IAClD,IAAI,EAAE,OAAO,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC;CACxC;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC;IACxD,WAAW,EAAE,OAAO,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC;CACzD;AAMD;;;;;;;GAOG;AACH,wBAAsB,qCAAqC,CACzD,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAwBjC;AAED;;;;;;;GAOG;AACH,wBAAsB,mCAAmC,CACvD,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAuBjC;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsB7B;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf;AAMD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,CAAC,CASzD;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqB7B;AAMD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC,oBAAoB,CAAC,YAAY,CAAC,EAAE,CAAC,CAS9D;AAED;;;;;;GAMG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC,oBAAoB,CAAC,YAAY,CAAC,EAAE,CAAC,CAQ9D;AAMD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC,iBAAiB,CAAC,YAAY,CAAC,EAAE,CAAC,CAS3D;AAMD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAW,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC,oBAAoB,CAAC,YAAY,CAAC,EAAE,CAAC,CAU9D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,OAAO,MAAM,CAAC,oBAAoB,CAAC,YAAY,EAC3D,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/store/lock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File locking using proper-lockfile.
+ * Prevents concurrent modifications to CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+/** A release function returned by acquireLock. */
+export type ReleaseFn = () => Promise<void>;
+/**
+ * Acquire an exclusive lock on a file.
+ * Returns a release function that must be called when done.
+ */
+export declare function acquireLock(filePath: string, options?: {
+    stale?: number;
+    retries?: number;
+}): Promise<ReleaseFn>;
+/**
+ * Check if a file is currently locked.
+ */
+export declare function isLocked(filePath: string): Promise<boolean>;
+/**
+ * Execute a function while holding an exclusive lock on a file.
+ * The lock is automatically released when the function completes (or throws).
+ */
+export declare function withLock<T>(filePath: string, fn: () => Promise<T>, options?: {
+    stale?: number;
+    retries?: number;
+}): Promise<T>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/store/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5C;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,SAAS,CAAC,CAmBpB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMjE;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/store/migration-sqlite.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Data migration: JSON to SQLite.
+ *
+ * One-time migration of todo.json + todo-archive.json + sessions.json → tasks.db.
+ * Validates row counts match after migration.
+ * Keeps JSON files as read-only backup (does not delete).
+ *
+ * @epic T4454
+ * @task W1-T5
+ * @task T4721 - Added atomic migration support with custom db path
+ */
+import type { Session, Task } from '@cleocode/contracts';
+/** Migration result. */
+export interface MigrationResult {
+    success: boolean;
+    tasksImported: number;
+    archivedImported: number;
+    sessionsImported: number;
+    errors: string[];
+    warnings: string[];
+    existingCounts?: {
+        tasks: number;
+        archived: number;
+        sessions: number;
+    };
+    jsonCounts?: {
+        tasks: number;
+        archived: number;
+        sessions: number;
+    };
+}
+/** Options for migration. */
+export interface MigrationOptions {
+    force?: boolean;
+    dryRun?: boolean;
+}
+/** Count records in JSON source files. */
+export declare function countJsonRecords(cleoDir: string): {
+    tasks: number;
+    archived: number;
+    sessions: number;
+};
+/**
+ * Migrate JSON data to SQLite.
+ * Reads todo.json, todo-archive.json, and sessions.json,
+ * writes to tasks.db via drizzle-orm.
+ */
+/**
+ * Migrate JSON data to SQLite with atomic rename pattern.
+ * Writes to a temporary database file first, then atomically renames.
+ *
+ * @param cwd - Optional working directory
+ * @param tempDbPath - Optional temporary database path for atomic migration
+ * @param logger - Optional migration logger for audit trail (@task T4727)
+ * @returns Migration result
+ */
+export declare function migrateJsonToSqliteAtomic(cwd?: string, tempDbPath?: string, logger?: import('../migration/logger.js').MigrationLogger): Promise<MigrationResult>;
+export declare function migrateJsonToSqlite(cwd?: string, options?: MigrationOptions): Promise<MigrationResult>;
+/**
+ * Export SQLite data back to JSON format (for inspection or emergency recovery).
+ */
+export declare function exportToJson(cwd?: string): Promise<{
+    tasks: Task[];
+    archived: Task[];
+    sessions: Session[];
+}>;
+//# sourceMappingURL=migration-sqlite.d.ts.map

package/dist/store/migration-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-sqlite.d.ts","sourceRoot":"","sources":["../../src/store/migration-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAwDzD,wBAAwB;AACxB,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE;QACf,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAoCA;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,CAAC,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,OAAO,wBAAwB,EAAE,eAAe,GACxD,OAAO,CAAC,eAAe,CAAC,CAuE1B;AAsRD,wBAAsB,mBAAmB,CACvC,GAAG,CAAC,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC,CAgR1B;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,CAAC,CA8BD"}