@cleocode/cleo 2026.2.5

package/dist/store/json-provider.js

@@ -0,0 +1,263 @@
+/**
+ * JSON StoreProvider implementation.
+ *
+ * Wraps existing JSON file operations (tasks, sessions, task work) behind
+ * the StoreProvider interface. This allows the CLI and MCP engine to
+ * use StoreProvider for all data access, switchable between JSON and SQLite.
+ *
+ * @task T4644
+ * @epic T4638
+ */
+import { createJsonDataAccessor } from './json-data-accessor.js';
+// Task operations
+import { addTask } from '../core/tasks/add.js';
+import { showTask } from '../core/tasks/show.js';
+import { updateTask } from '../core/tasks/update.js';
+import { completeTask } from '../core/tasks/complete.js';
+import { listTasks } from '../core/tasks/list.js';
+import { findTasks } from '../core/tasks/find.js';
+import { archiveTasks } from '../core/tasks/archive.js';
+import { deleteTask } from '../core/tasks/delete.js';
+// Session operations
+import { startSession, endSession, sessionStatus, listSessions, resumeSession, gcSessions, } from '../core/sessions/index.js';
+// Task work operations
+import { startTask, currentTask, stopTask, getWorkHistory } from '../core/task-work/index.js';
+// Label operations
+import { listLabels, showLabelTasks, getLabelStats } from '../core/tasks/labels.js';
+// Relationship operations
+import { suggestRelated, addRelation, discoverRelated, listRelations } from '../core/tasks/relates.js';
+// Analysis operations
+import { analyzeTaskPriority } from '../core/tasks/analyze.js';
+/**
+ * Create a JSON-backed StoreProvider.
+ *
+ * Delegates to existing core module functions that read/write JSON files.
+ * A JsonDataAccessor is created once and passed to all core calls, ensuring
+ * consistent storage access throughout the provider's lifetime.
+ *
+ * @task T4644
+ * @epic T4638
+ */
+export function createJsonStoreProvider(cwd) {
+    // Create a JSON accessor once (lazy, cached), shared by all domain operations.
+    let _accessorPromise = null;
+    function getAcc() {
+        if (!_accessorPromise) {
+            _accessorPromise = createJsonDataAccessor(cwd);
+        }
+        return _accessorPromise;
+    }
+    return {
+        engine: 'json',
+        // ---- Task CRUD ----
+        createTask: async (task) => {
+            const acc = await getAcc();
+            const result = await addTask({
+                title: task.title,
+                status: task.status,
+                priority: task.priority,
+                type: task.type,
+                parentId: task.parentId,
+                size: task.size ?? undefined,
+                phase: task.phase,
+                description: task.description,
+                labels: task.labels,
+                depends: task.depends,
+            }, cwd, acc);
+            return result.task;
+        },
+        getTask: async (taskId) => {
+            try {
+                const acc = await getAcc();
+                const detail = await showTask(taskId, cwd, acc);
+                return detail;
+            }
+            catch {
+                return null;
+            }
+        },
+        updateTask: async (taskId, updates) => {
+            try {
+                const acc = await getAcc();
+                const result = await updateTask({
+                    taskId,
+                    title: updates.title,
+                    status: updates.status,
+                    priority: updates.priority,
+                    type: updates.type,
+                    size: updates.size ?? undefined,
+                    phase: updates.phase,
+                    description: updates.description,
+                    labels: updates.labels,
+                    depends: updates.depends,
+                    blockedBy: updates.blockedBy,
+                }, cwd, acc);
+                return result.task;
+            }
+            catch {
+                return null;
+            }
+        },
+        deleteTask: async (taskId) => {
+            try {
+                const acc = await getAcc();
+                await deleteTask({ taskId, force: true }, cwd, acc);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        listTasks: async (filters) => {
+            const acc = await getAcc();
+            const result = await listTasks({
+                status: filters?.status,
+                parentId: filters?.parentId ?? undefined,
+                type: filters?.type,
+                phase: filters?.phase,
+                limit: filters?.limit,
+            }, cwd, acc);
+            return result.tasks;
+        },
+        findTasks: async (query, limit) => {
+            const acc = await getAcc();
+            const result = await findTasks({ query, limit }, cwd, acc);
+            // findTasks returns FindResult (minimal fields), but StoreProvider expects Task.
+            // We need to fetch full task details for each result.
+            const tasks = [];
+            for (const r of result.results) {
+                try {
+                    const detail = await showTask(r.id, cwd, acc);
+                    tasks.push(detail);
+                }
+                catch {
+                    // Skip tasks that can't be loaded
+                }
+            }
+            return tasks;
+        },
+        archiveTask: async (taskId, _reason) => {
+            try {
+                const acc = await getAcc();
+                const result = await archiveTasks({ taskIds: [taskId] }, cwd, acc);
+                return result.archived.includes(taskId);
+            }
+            catch {
+                return false;
+            }
+        },
+        // ---- Session CRUD ----
+        createSession: async (session) => {
+            const acc = await getAcc();
+            const result = await startSession({
+                name: session.name,
+                scope: session.scope.type === 'epic' && session.scope.epicId
+                    ? `epic:${session.scope.epicId}`
+                    : 'global',
+                startTask: session.taskWork?.taskId ?? undefined,
+                agent: session.agent ?? undefined,
+            }, cwd, acc);
+            return result;
+        },
+        getSession: async (sessionId) => {
+            const acc = await getAcc();
+            const sessions = await listSessions({}, cwd, acc);
+            return sessions.find(s => s.id === sessionId) ?? null;
+        },
+        updateSession: async (sessionId, updates) => {
+            const acc = await getAcc();
+            // JSON sessions don't have a generic update; status changes go through end/resume
+            if (updates.status === 'ended') {
+                try {
+                    const result = await endSession({ sessionId }, cwd, acc);
+                    return result;
+                }
+                catch {
+                    return null;
+                }
+            }
+            if (updates.status === 'active') {
+                try {
+                    const result = await resumeSession(sessionId, cwd, acc);
+                    return result;
+                }
+                catch {
+                    return null;
+                }
+            }
+            // For other updates, return the session as-is
+            const sessions = await listSessions({}, cwd, acc);
+            return sessions.find(s => s.id === sessionId) ?? null;
+        },
+        listSessions: async (filters) => {
+            const acc = await getAcc();
+            const opts = {};
+            if (filters?.active)
+                opts.status = 'active';
+            if (filters?.limit)
+                opts.limit = filters.limit;
+            return listSessions(opts, cwd, acc);
+        },
+        endSession: async (sessionId, note) => {
+            try {
+                const acc = await getAcc();
+                return await endSession({ sessionId, note }, cwd, acc);
+            }
+            catch {
+                return null;
+            }
+        },
+        // ---- Task work (session-level) ----
+        startTaskOnSession: async (_sessionId, taskId) => {
+            const acc = await getAcc();
+            await startTask(taskId, cwd, acc);
+        },
+        getCurrentTaskForSession: async (_sessionId) => {
+            const acc = await getAcc();
+            const current = await currentTask(cwd, acc);
+            return {
+                taskId: current.currentTask,
+                since: null, // JSON storage doesn't track 'since' per session
+            };
+        },
+        stopTaskOnSession: async (_sessionId) => {
+            const acc = await getAcc();
+            await stopTask(cwd, acc);
+        },
+        // ---- Lifecycle ----
+        close: async () => {
+            // No-op for JSON provider -- no connections to close
+        },
+        // ---- High-level domain operations ----
+        // All domain ops pass the accessor so the correct storage engine is used.
+        // @task T4656
+        // @epic T4654
+        addTask: async (options) => { const acc = await getAcc(); return addTask(options, cwd, acc); },
+        completeTask: async (options) => { const acc = await getAcc(); return completeTask(options, cwd, acc); },
+        richUpdateTask: async (options) => { const acc = await getAcc(); return updateTask(options, cwd, acc); },
+        showTask: async (taskId) => { const acc = await getAcc(); return showTask(taskId, cwd, acc); },
+        richDeleteTask: async (options) => { const acc = await getAcc(); return deleteTask(options, cwd, acc); },
+        richFindTasks: async (options) => { const acc = await getAcc(); return findTasks(options, cwd, acc); },
+        richListTasks: async (options) => { const acc = await getAcc(); return listTasks(options, cwd, acc); },
+        richArchiveTasks: async (options) => { const acc = await getAcc(); return archiveTasks(options, cwd, acc); },
+        startSession: async (options) => { const acc = await getAcc(); return startSession(options, cwd, acc); },
+        richEndSession: async (options) => { const acc = await getAcc(); return endSession(options, cwd, acc); },
+        sessionStatus: async () => { const acc = await getAcc(); return sessionStatus(cwd, acc); },
+        resumeSession: async (sessionId) => { const acc = await getAcc(); return resumeSession(sessionId, cwd, acc); },
+        richListSessions: async (options) => { const acc = await getAcc(); return listSessions(options, cwd, acc); },
+        gcSessions: async (maxAgeHours) => { const acc = await getAcc(); return gcSessions(maxAgeHours, cwd, acc); },
+        currentTask: async () => { const acc = await getAcc(); return currentTask(cwd, acc); },
+        startTask: async (taskId) => { const acc = await getAcc(); return startTask(taskId, cwd, acc); },
+        stopTask: async () => { const acc = await getAcc(); return stopTask(cwd, acc); },
+        getWorkHistory: async () => { const acc = await getAcc(); return getWorkHistory(cwd, acc); },
+        listLabels: async () => { const acc = await getAcc(); return listLabels(cwd, acc); },
+        showLabelTasks: async (label) => { const acc = await getAcc(); return showLabelTasks(label, cwd, acc); },
+        getLabelStats: async () => { const acc = await getAcc(); return getLabelStats(cwd, acc); },
+        suggestRelated: async (taskId, opts) => { const acc = await getAcc(); return suggestRelated(taskId, { ...opts, cwd }, acc); },
+        addRelation: async (from, to, type, reason) => { const acc = await getAcc(); return addRelation(from, to, type, reason, cwd, acc); },
+        discoverRelated: async (taskId) => { const acc = await getAcc(); return discoverRelated(taskId, cwd, acc); },
+        listRelations: async (taskId) => { const acc = await getAcc(); return listRelations(taskId, cwd, acc); },
+        analyzeTaskPriority: async (opts) => { const acc = await getAcc(); return analyzeTaskPriority({ ...opts, cwd }, acc); },
+    };
+}
+//# sourceMappingURL=json-provider.js.map

package/dist/store/json-provider.js.map

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

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,CAa/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAShF;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,CA2Bf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAkFzF"}

package/dist/store/json.js

@@ -0,0 +1,198 @@
+/**
+ * JSON read/write with schema validation, locking, and backup.
+ * This is the primary data access layer for CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+import { createHash } from 'node:crypto';
+import { atomicWrite, atomicWriteJson, safeReadFile } from './atomic.js';
+import { createBackup } from './backup.js';
+import { withLock } from './lock.js';
+import { CleoError } from '../core/errors.js';
+import { ExitCode } from '../types/exit-codes.js';
+/**
+ * Read and parse a JSON file.
+ * Returns null if the file does not exist.
+ */
+export async function readJson(filePath) {
+    const content = await safeReadFile(filePath);
+    if (content === null)
+        return null;
+    try {
+        return JSON.parse(content);
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `Invalid JSON in: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * Read a JSON file, throwing if it doesn't exist.
+ */
+export async function readJsonRequired(filePath) {
+    const data = await readJson(filePath);
+    if (data === null) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Required file not found: ${filePath}`);
+    }
+    return data;
+}
+/**
+ * Compute a truncated SHA-256 checksum of a value.
+ * Used for integrity verification (matches Bash CLI's 16-char hex format).
+ */
+export function computeChecksum(data) {
+    const json = JSON.stringify(data);
+    const hash = createHash('sha256').update(json).digest('hex');
+    return hash.substring(0, 16);
+}
+/**
+ * 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 async function saveJson(filePath, data, options) {
+    await withLock(filePath, async () => {
+        // Validate before write
+        if (options?.validate) {
+            try {
+                await options.validate(data);
+            }
+            catch (err) {
+                throw new CleoError(ExitCode.VALIDATION_ERROR, `Validation failed before write: ${filePath}`, { cause: err });
+            }
+        }
+        // Create backup if configured
+        if (options?.backupDir) {
+            try {
+                await createBackup(filePath, options.backupDir, options.maxBackups);
+            }
+            catch {
+                // Backup failure is non-fatal for first write (file may not exist yet)
+            }
+        }
+        // Atomic write
+        await atomicWriteJson(filePath, data, { indent: options?.indent });
+    });
+}
+/**
+ * Append a line to a JSONL file atomically.
+ * Used for manifest entries and audit logs.
+ */
+export async function appendJsonl(filePath, entry) {
+    const existing = await safeReadFile(filePath);
+    const line = JSON.stringify(entry);
+    const content = existing ? existing.trimEnd() + '\n' + line + '\n' : line + '\n';
+    await atomicWrite(filePath, content);
+}
+/**
+ * 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 async function readLogEntries(filePath) {
+    const content = await safeReadFile(filePath);
+    if (content === null)
+        return [];
+    const trimmed = content.trim();
+    if (!trimmed)
+        return [];
+    // Fast path: try parsing as a single JSON object
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed && typeof parsed === 'object' && Array.isArray(parsed.entries)) {
+            return parsed.entries;
+        }
+        // Single object, wrap in array
+        return [parsed];
+    }
+    catch {
+        // Not valid JSON - handle hybrid format
+    }
+    // Hybrid format: find where the initial JSON object ends, then parse JSONL after it
+    const entries = [];
+    if (trimmed.startsWith('{')) {
+        // Find the matching closing brace for the initial JSON object
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        let jsonEnd = -1;
+        for (let i = 0; i < trimmed.length; i++) {
+            const ch = trimmed[i];
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === '\\' && inString) {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (inString)
+                continue;
+            if (ch === '{')
+                depth++;
+            else if (ch === '}') {
+                depth--;
+                if (depth === 0) {
+                    jsonEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        if (jsonEnd > 0) {
+            // Parse the initial JSON object
+            try {
+                const initialJson = JSON.parse(trimmed.substring(0, jsonEnd));
+                if (initialJson && Array.isArray(initialJson.entries)) {
+                    entries.push(...initialJson.entries);
+                }
+            }
+            catch {
+                // Corrupted initial JSON - skip it
+            }
+            // Parse remaining lines as JSONL
+            const remainder = trimmed.substring(jsonEnd).trim();
+            if (remainder) {
+                for (const line of remainder.split('\n')) {
+                    const l = line.trim();
+                    if (!l || !l.startsWith('{'))
+                        continue;
+                    try {
+                        entries.push(JSON.parse(l));
+                    }
+                    catch {
+                        // Skip unparseable lines
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // Pure JSONL (no initial JSON object)
+        for (const line of trimmed.split('\n')) {
+            const l = line.trim();
+            if (!l || !l.startsWith('{'))
+                continue;
+            try {
+                entries.push(JSON.parse(l));
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=json.js.map

package/dist/store/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/store/json.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAc,QAAgB;IAC1D,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAElC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,gBAAgB,EACzB,oBAAoB,QAAQ,EAAE,EAC9B,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAc,QAAgB;IAClE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAI,QAAQ,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,SAAS,EAClB,4BAA4B,QAAQ,EAAE,CACvC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAgB,EAChB,IAAa,EACb,OAAyB;IAEzB,MAAM,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAClC,wBAAwB;QACxB,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,gBAAgB,EACzB,mCAAmC,QAAQ,EAAE,EAC7C,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;QACH,CAAC;QAED,8BAA8B;QAC9B,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YACtE,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;YACzE,CAAC;QACH,CAAC;QAED,eAAe;QACf,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,KAAc;IAEd,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;IACjF,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB;IACnD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,iDAAiD;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,MAAmC,CAAC;QACtE,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1E,OAAO,MAAM,CAAC,OAAoC,CAAC;QACrD,CAAC;QACD,+BAA+B;QAC/B,OAAO,CAAC,MAAiC,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;IAC1C,CAAC;IAED,oFAAoF;IACpF,MAAM,OAAO,GAA8B,EAAE,CAAC;IAE9C,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,8DAA8D;QAC9D,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;QAEjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;YACvB,IAAI,OAAO,EAAE,CAAC;gBAAC,OAAO,GAAG,KAAK,CAAC;gBAAC,SAAS;YAAC,CAAC;YAC3C,IAAI,EAAE,KAAK,IAAI,IAAI,QAAQ,EAAE,CAAC;gBAAC,OAAO,GAAG,IAAI,CAAC;gBAAC,SAAS;YAAC,CAAC;YAC1D,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBAAC,QAAQ,GAAG,CAAC,QAAQ,CAAC;gBAAC,SAAS;YAAC,CAAC;YACnD,IAAI,QAAQ;gBAAE,SAAS;YACvB,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;iBACnB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACpB,KAAK,EAAE,CAAC;gBACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;oBAAC,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;oBAAC,MAAM;gBAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAED,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,gCAAgC;YAChC,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC9D,IAAI,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;oBACtD,OAAO,CAAC,IAAI,CAAC,GAAI,WAAW,CAAC,OAAqC,CAAC,CAAC;gBACtE,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;YAED,iCAAiC;YACjC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YACpD,IAAI,SAAS,EAAE,CAAC;gBACd,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;oBACzC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;oBACtB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,SAAS;oBACvC,IAAI,CAAC;wBACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAA4B,CAAC,CAAC;oBACzD,CAAC;oBAAC,MAAM,CAAC;wBACP,yBAAyB;oBAC3B,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,sCAAsC;QACtC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACvC,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAA4B,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

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,CAuBpB;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/lock.js

@@ -0,0 +1,70 @@
+/**
+ * File locking using proper-lockfile.
+ * Prevents concurrent modifications to CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+import lockfile from 'proper-lockfile';
+import { CleoError } from '../core/errors.js';
+import { ExitCode } from '../types/exit-codes.js';
+/** Default lock options. */
+const DEFAULT_LOCK_OPTIONS = {
+    retries: {
+        retries: 3,
+        minTimeout: 100,
+        maxTimeout: 1000,
+        factor: 2,
+    },
+    stale: 10_000,
+    realpath: false,
+};
+/**
+ * Acquire an exclusive lock on a file.
+ * Returns a release function that must be called when done.
+ */
+export async function acquireLock(filePath, options) {
+    try {
+        const release = await lockfile.lock(filePath, {
+            ...DEFAULT_LOCK_OPTIONS,
+            ...(options?.stale !== undefined && { stale: options.stale }),
+            ...(options?.retries !== undefined && {
+                retries: {
+                    ...DEFAULT_LOCK_OPTIONS.retries,
+                    retries: options.retries,
+                },
+            }),
+        });
+        return release;
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.LOCK_TIMEOUT, `Failed to acquire lock: ${filePath}`, {
+            fix: `Another process may be writing to this file. Wait and retry.`,
+            cause: err,
+        });
+    }
+}
+/**
+ * Check if a file is currently locked.
+ */
+export async function isLocked(filePath) {
+    try {
+        return await lockfile.check(filePath, { realpath: false });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute a function while holding an exclusive lock on a file.
+ * The lock is automatically released when the function completes (or throws).
+ */
+export async function withLock(filePath, fn, options) {
+    const release = await acquireLock(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/store/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,4BAA4B;AAC5B,MAAM,oBAAoB,GAAG;IAC3B,OAAO,EAAE;QACP,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,CAAC;KACV;IACD,KAAK,EAAE,MAAM;IACb,QAAQ,EAAE,KAAK;CAChB,CAAC;AAKF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,OAA8C;IAE9C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC5C,GAAG,oBAAoB;YACvB,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC7D,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,IAAI;gBACpC,OAAO,EAAE;oBACP,GAAG,oBAAoB,CAAC,OAAO;oBAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;iBACzB;aACF,CAAC;SACH,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,YAAY,EACrB,2BAA2B,QAAQ,EAAE,EACrC;YACE,GAAG,EAAE,8DAA8D;YACnE,KAAK,EAAE,GAAG;SACX,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAgB,EAChB,EAAoB,EACpB,OAA8C;IAE9C,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC"}