@ginkoai/cli 2.0.6 → 2.1.1

package/dist/lib/state-cache.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-01-19
+ * @tags: [cache, offline, state, EPIC-015]
+ * @related: [staleness-detector.ts, user-sprint.ts, start-reflection.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, path]
+ */
+/**
+ * Data about the active sprint for display
+ */
+export interface ActiveSprintData {
+    sprintId: string;
+    sprintName: string;
+    epicId: string;
+    epicName?: string;
+    progress: {
+        completed: number;
+        total: number;
+        percentage: number;
+    };
+    currentTask?: {
+        taskId: string;
+        taskName: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    };
+    nextTask?: {
+        taskId: string;
+        taskName: string;
+    };
+}
+/**
+ * Cached state structure
+ */
+export interface StateCache {
+    version: 1;
+    fetched_at: string;
+    graph_id: string;
+    active_sprint: ActiveSprintData;
+}
+/**
+ * Result of checking cache staleness
+ */
+export interface CacheStalenessResult {
+    level: 'fresh' | 'stale' | 'expired';
+    age: number;
+    ageHuman: string;
+    isFresh: boolean;
+    showWarning: boolean;
+}
+/**
+ * Load cached state from disk
+ *
+ * @returns StateCache if valid cache exists, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const cache = await loadStateCache();
+ * if (cache) {
+ *   console.log(`Sprint: ${cache.active_sprint.sprintName}`);
+ * }
+ * ```
+ */
+export declare function loadStateCache(): Promise<StateCache | null>;
+/**
+ * Save state data to cache
+ * Uses atomic write (temp file + rename) to prevent partial writes
+ *
+ * @param data - Active sprint data to cache
+ * @param graphId - The graph ID this data belongs to
+ *
+ * @example
+ * ```typescript
+ * await saveStateCache(sprintData, 'graph-123');
+ * ```
+ */
+export declare function saveStateCache(data: ActiveSprintData, graphId: string): Promise<void>;
+/**
+ * Clear the state cache
+ * Called when cache should be invalidated (e.g., logout, graph switch)
+ *
+ * @example
+ * ```typescript
+ * await clearStateCache();
+ * ```
+ */
+export declare function clearStateCache(): Promise<void>;
+/**
+ * Check staleness of cached state
+ *
+ * Staleness levels:
+ * - fresh: < 5 minutes old
+ * - stale: 5 minutes to 24 hours old
+ * - expired: > 24 hours old
+ *
+ * @param cache - The cached state to check
+ * @returns Staleness result with level, age, and display info
+ *
+ * @example
+ * ```typescript
+ * const cache = await loadStateCache();
+ * if (cache) {
+ *   const staleness = checkCacheStaleness(cache);
+ *   if (staleness.showWarning) {
+ *     console.log(`Cache is ${staleness.level}: ${staleness.ageHuman}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function checkCacheStaleness(cache: StateCache): CacheStalenessResult;
+/**
+ * Format cache age for human-readable display
+ *
+ * @param fetchedAt - ISO timestamp string
+ * @returns Human-readable age string (e.g., "15 min ago", "2 hours ago")
+ *
+ * @example
+ * ```typescript
+ * const age = formatCacheAge('2026-01-19T10:00:00.000Z');
+ * // Returns something like "15 min ago"
+ * ```
+ */
+export declare function formatCacheAge(fetchedAt: string): string;
+/**
+ * Get the full path to the cache file
+ */
+declare function getCachePath(): Promise<string>;
+/**
+ * Validate that cache data has correct structure and version
+ */
+declare function isValidCache(data: unknown): data is StateCache;
+export declare const _internal: {
+    getCachePath: typeof getCachePath;
+    isValidCache: typeof isValidCache;
+    FRESH_THRESHOLD_MS: number;
+    EXPIRED_THRESHOLD_MS: number;
+    CACHE_VERSION: number;
+};
+export {};
+//# sourceMappingURL=state-cache.d.ts.map

package/dist/lib/state-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/lib/state-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;KACjD,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,gBAAgB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAoBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAUrD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,oBAAoB,CAsB3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAMD;;GAEG;AACH,iBAAe,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAG7C;AAED;;GAEG;AACH,iBAAS,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU,CAsCvD;AAMD,eAAO,MAAM,SAAS;;;;;;CAMrB,CAAC"}

package/dist/lib/state-cache.js

@@ -0,0 +1,259 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-01-19
+ * @tags: [cache, offline, state, EPIC-015]
+ * @related: [staleness-detector.ts, user-sprint.ts, start-reflection.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, path]
+ */
+/**
+ * Local State Cache (EPIC-015 Sprint 2)
+ *
+ * Provides local caching for API state data to enable:
+ * - Offline operation when API is unavailable
+ * - Faster startup by avoiding API calls for fresh data
+ * - Graceful degradation with staleness indicators
+ *
+ * Cache location: .ginko/state-cache.json
+ * Uses atomic writes (temp file + rename) to prevent partial writes.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { getGinkoDir } from '../utils/helpers.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const CACHE_FILE = 'state-cache.json';
+const CACHE_VERSION = 1;
+// Staleness thresholds in milliseconds
+const FRESH_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+const EXPIRED_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
+// =============================================================================
+// Main API
+// =============================================================================
+/**
+ * Load cached state from disk
+ *
+ * @returns StateCache if valid cache exists, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const cache = await loadStateCache();
+ * if (cache) {
+ *   console.log(`Sprint: ${cache.active_sprint.sprintName}`);
+ * }
+ * ```
+ */
+export async function loadStateCache() {
+    try {
+        const cachePath = await getCachePath();
+        if (!await fs.pathExists(cachePath)) {
+            return null;
+        }
+        const data = await fs.readJSON(cachePath);
+        // Validate cache version and required fields
+        if (!isValidCache(data)) {
+            return null;
+        }
+        return data;
+    }
+    catch (error) {
+        // File doesn't exist, is invalid JSON, or other read error
+        return null;
+    }
+}
+/**
+ * Save state data to cache
+ * Uses atomic write (temp file + rename) to prevent partial writes
+ *
+ * @param data - Active sprint data to cache
+ * @param graphId - The graph ID this data belongs to
+ *
+ * @example
+ * ```typescript
+ * await saveStateCache(sprintData, 'graph-123');
+ * ```
+ */
+export async function saveStateCache(data, graphId) {
+    const cachePath = await getCachePath();
+    const cacheDir = path.dirname(cachePath);
+    const tempPath = `${cachePath}.tmp.${Date.now()}`;
+    // Ensure .ginko directory exists
+    await fs.ensureDir(cacheDir);
+    const cache = {
+        version: CACHE_VERSION,
+        fetched_at: new Date().toISOString(),
+        graph_id: graphId,
+        active_sprint: data,
+    };
+    // Atomic write: write to temp file, then rename
+    try {
+        await fs.writeJSON(tempPath, cache, { spaces: 2 });
+        await fs.rename(tempPath, cachePath);
+    }
+    catch (error) {
+        // Clean up temp file if rename failed
+        try {
+            await fs.remove(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+/**
+ * Clear the state cache
+ * Called when cache should be invalidated (e.g., logout, graph switch)
+ *
+ * @example
+ * ```typescript
+ * await clearStateCache();
+ * ```
+ */
+export async function clearStateCache() {
+    try {
+        const cachePath = await getCachePath();
+        if (await fs.pathExists(cachePath)) {
+            await fs.remove(cachePath);
+        }
+    }
+    catch (error) {
+        // Ignore errors when clearing cache
+    }
+}
+/**
+ * Check staleness of cached state
+ *
+ * Staleness levels:
+ * - fresh: < 5 minutes old
+ * - stale: 5 minutes to 24 hours old
+ * - expired: > 24 hours old
+ *
+ * @param cache - The cached state to check
+ * @returns Staleness result with level, age, and display info
+ *
+ * @example
+ * ```typescript
+ * const cache = await loadStateCache();
+ * if (cache) {
+ *   const staleness = checkCacheStaleness(cache);
+ *   if (staleness.showWarning) {
+ *     console.log(`Cache is ${staleness.level}: ${staleness.ageHuman}`);
+ *   }
+ * }
+ * ```
+ */
+export function checkCacheStaleness(cache) {
+    const fetchedAt = new Date(cache.fetched_at);
+    const now = new Date();
+    const ageMs = now.getTime() - fetchedAt.getTime();
+    let level;
+    if (ageMs < FRESH_THRESHOLD_MS) {
+        level = 'fresh';
+    }
+    else if (ageMs < EXPIRED_THRESHOLD_MS) {
+        level = 'stale';
+    }
+    else {
+        level = 'expired';
+    }
+    return {
+        level,
+        age: ageMs,
+        ageHuman: formatCacheAge(cache.fetched_at),
+        isFresh: level === 'fresh',
+        showWarning: level !== 'fresh',
+    };
+}
+/**
+ * Format cache age for human-readable display
+ *
+ * @param fetchedAt - ISO timestamp string
+ * @returns Human-readable age string (e.g., "15 min ago", "2 hours ago")
+ *
+ * @example
+ * ```typescript
+ * const age = formatCacheAge('2026-01-19T10:00:00.000Z');
+ * // Returns something like "15 min ago"
+ * ```
+ */
+export function formatCacheAge(fetchedAt) {
+    const date = new Date(fetchedAt);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffSecs = Math.floor(diffMs / 1000);
+    const diffMins = Math.floor(diffMs / (1000 * 60));
+    const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffSecs < 60) {
+        return 'just now';
+    }
+    if (diffMins < 60) {
+        return `${diffMins} min ago`;
+    }
+    if (diffHours < 24) {
+        return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`;
+    }
+    if (diffDays < 7) {
+        return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
+    }
+    return date.toLocaleDateString();
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get the full path to the cache file
+ */
+async function getCachePath() {
+    const ginkoDir = await getGinkoDir();
+    return path.join(ginkoDir, CACHE_FILE);
+}
+/**
+ * Validate that cache data has correct structure and version
+ */
+function isValidCache(data) {
+    if (!data || typeof data !== 'object') {
+        return false;
+    }
+    const cache = data;
+    // Check version
+    if (cache.version !== CACHE_VERSION) {
+        return false;
+    }
+    // Check required fields
+    if (!cache.fetched_at || typeof cache.fetched_at !== 'string') {
+        return false;
+    }
+    if (!cache.graph_id || typeof cache.graph_id !== 'string') {
+        return false;
+    }
+    if (!cache.active_sprint || typeof cache.active_sprint !== 'object') {
+        return false;
+    }
+    // Validate active_sprint structure
+    const sprint = cache.active_sprint;
+    if (!sprint.sprintId || !sprint.sprintName || !sprint.epicId) {
+        return false;
+    }
+    if (!sprint.progress || typeof sprint.progress.completed !== 'number' ||
+        typeof sprint.progress.total !== 'number' ||
+        typeof sprint.progress.percentage !== 'number') {
+        return false;
+    }
+    return true;
+}
+// =============================================================================
+// Exports for Testing
+// =============================================================================
+export const _internal = {
+    getCachePath,
+    isValidCache,
+    FRESH_THRESHOLD_MS,
+    EXPIRED_THRESHOLD_MS,
+    CACHE_VERSION,
+};
+//# sourceMappingURL=state-cache.js.map

package/dist/lib/state-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-cache.js","sourceRoot":"","sources":["../../src/lib/state-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAmDlD,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,uCAAuC;AACvC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAM,YAAY;AAC3D,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW;AAE7D,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;QAEvC,IAAI,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAE1C,6CAA6C;QAC7C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAkB,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2DAA2D;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAsB,EACtB,OAAe;IAEf,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,SAAS,QAAQ,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAElD,iCAAiC;IACjC,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE7B,MAAM,KAAK,GAAe;QACxB,OAAO,EAAE,aAAa;QACtB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,OAAO;QACjB,aAAa,EAAE,IAAI;KACpB,CAAC;IAEF,gDAAgD;IAChD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,YAAY,EAAE,CAAC;QAEvC,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oCAAoC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;IAElD,IAAI,KAAoC,CAAC;IAEzC,IAAI,KAAK,GAAG,kBAAkB,EAAE,CAAC;QAC/B,KAAK,GAAG,OAAO,CAAC;IAClB,CAAC;SAAM,IAAI,KAAK,GAAG,oBAAoB,EAAE,CAAC;QACxC,KAAK,GAAG,OAAO,CAAC;IAClB,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;IAED,OAAO;QACL,KAAK;QACL,GAAG,EAAE,KAAK;QACV,QAAQ,EAAE,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC;QAC1C,OAAO,EAAE,KAAK,KAAK,OAAO;QAC1B,WAAW,EAAE,KAAK,KAAK,OAAO;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAE5D,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;QAClB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;QAClB,OAAO,GAAG,QAAQ,UAAU,CAAC;IAC/B,CAAC;IACD,IAAI,SAAS,GAAG,EAAE,EAAE,CAAC;QACnB,OAAO,GAAG,SAAS,QAAQ,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC9D,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,GAAG,QAAQ,OAAO,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC3D,CAAC;IAED,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC;AACnC,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,KAAK,UAAU,YAAY;IACzB,MAAM,QAAQ,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,IAAa;IACjC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,IAA2B,CAAC;IAE1C,gBAAgB;IAChB,IAAI,KAAK,CAAC,OAAO,KAAK,aAAa,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC9D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mCAAmC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,KAAK,QAAQ;QACjE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,QAAQ;QACzC,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,YAAY;IACZ,YAAY;IACZ,kBAAkB;IAClB,oBAAoB;IACpB,aAAa;CACd,CAAC"}

package/dist/lib/targeted-coaching.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-01-26
+ * @tags: [coaching, insights, targeted, adaptive, epic-016-s05]
+ * @related: [coaching-level.ts, start-reflection.ts, handoff.ts]
+ * @priority: medium
+ * @complexity: medium
+ * @dependencies: [fs-extra, path]
+ */
+import { CoachingContext } from './coaching-level.js';
+export type MetricType = 'sessionEfficiency' | 'patternAdoption' | 'collaborationQuality' | 'antiPatterns';
+export type CoachingContext_Type = 'start' | 'handoff' | 'task_complete' | 'planning';
+export interface CoachingTip {
+    id: string;
+    metric: MetricType;
+    context: CoachingContext_Type[];
+    message: string;
+    action?: string;
+    priority: number;
+}
+export interface ShownTipsRecord {
+    sessionId: string;
+    shownTipIds: string[];
+    lastUpdated: string;
+}
+/**
+ * All available coaching tips organized by metric
+ */
+export declare const COACHING_TIPS: CoachingTip[];
+declare function loadShownTips(): Promise<ShownTipsRecord>;
+declare function saveShownTips(record: ShownTipsRecord): Promise<void>;
+declare function markTipAsShown(tipId: string): Promise<void>;
+declare function isTipShown(tipId: string): Promise<boolean>;
+/**
+ * Get applicable tips for a given context and coaching context
+ *
+ * @param coachingCtx - Coaching context with metric scores
+ * @param context - Current context (start, handoff, etc.)
+ * @param limit - Maximum number of tips to return
+ * @returns Array of applicable tips, prioritized
+ */
+export declare function getApplicableTips(coachingCtx: CoachingContext, context: CoachingContext_Type, limit?: number): Promise<CoachingTip[]>;
+declare function getMetricValue(ctx: CoachingContext, metric: MetricType): number;
+/**
+ * Display a coaching tip to the console
+ */
+export declare function displayTip(tip: CoachingTip): void;
+/**
+ * Show targeted coaching tips for the current context
+ *
+ * @param coachingCtx - Coaching context with metric scores
+ * @param context - Current context
+ * @returns Number of tips shown
+ */
+export declare function showTargetedCoaching(coachingCtx: CoachingContext, context: CoachingContext_Type): Promise<number>;
+/**
+ * Get coaching tip for a specific metric (for inline use)
+ */
+export declare function getTipForMetric(coachingCtx: CoachingContext, metric: MetricType, context: CoachingContext_Type): Promise<string | null>;
+export declare const METRIC_DISPLAY_NAMES: Record<MetricType, string>;
+export declare const __testing: {
+    LOW_THRESHOLD: number;
+    loadShownTips: typeof loadShownTips;
+    saveShownTips: typeof saveShownTips;
+    markTipAsShown: typeof markTipAsShown;
+    isTipShown: typeof isTipShown;
+    getMetricValue: typeof getMetricValue;
+};
+export {};
+//# sourceMappingURL=targeted-coaching.d.ts.map

package/dist/lib/targeted-coaching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeted-coaching.d.ts","sourceRoot":"","sources":["../../src/lib/targeted-coaching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyBH,OAAO,EAAE,eAAe,EAAe,MAAM,qBAAqB,CAAC;AAOnE,MAAM,MAAM,UAAU,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,sBAAsB,GAAG,cAAc,CAAC;AAC3G,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,GAAG,eAAe,GAAG,UAAU,CAAC;AAEtF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AASD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAmGtC,CAAC;AAaF,iBAAe,aAAa,IAAI,OAAO,CAAC,eAAe,CAAC,CA0BvD;AAED,iBAAe,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnE;AAMD,iBAAe,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM1D;AAED,iBAAe,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGzD;AAMD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,eAAe,EAC5B,OAAO,EAAE,oBAAoB,EAC7B,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC,WAAW,EAAE,CAAC,CAiCxB;AAED,iBAAS,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAWxE;AAMD;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAQjD;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,eAAe,EAC5B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,eAAe,EAC5B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAmBD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAK3D,CAAC;AAMF,eAAO,MAAM,SAAS;;;;;;;CAOrB,CAAC"}