@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/episodes/store.js

@@ -0,0 +1,199 @@
+/**
+ * File-Based Episode Store
+ *
+ * Persists work episodes to a JSON file per project.
+ * Uses an in-memory cache — all reads are synchronous, writes are async (fire-and-forget).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { EFFORT_ORDER } from '@compilr-dev/agents';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_MAX_EPISODES = 1000;
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// =============================================================================
+// Implementation
+// =============================================================================
+export class FileEpisodeStore {
+    filePath;
+    maxEpisodes;
+    maxAgeMs;
+    _episodes = null; // lazy-loaded
+    flushPromise = null;
+    constructor(options) {
+        this.filePath = options.filePath;
+        this.maxEpisodes = options.maxEpisodes ?? DEFAULT_MAX_EPISODES;
+        this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    }
+    /** Lazy-load and return the in-memory episode cache */
+    get episodes() {
+        if (this._episodes === null) {
+            this._episodes = this.loadFromDisk();
+        }
+        return this._episodes;
+    }
+    // ---------------------------------------------------------------------------
+    // Write methods
+    // ---------------------------------------------------------------------------
+    save(episode) {
+        this.episodes.push(episode);
+        void this.flush();
+    }
+    saveBatch(episodes) {
+        if (episodes.length === 0)
+            return;
+        this.episodes.push(...episodes);
+        void this.flush();
+    }
+    // ---------------------------------------------------------------------------
+    // Read methods (synchronous — read from cache)
+    // ---------------------------------------------------------------------------
+    getAll() {
+        return [...this.episodes];
+    }
+    getByFiles(files) {
+        const fileSet = new Set(files);
+        return this.episodes.filter((ep) => ep.files.some((f) => fileSet.has(f)));
+    }
+    getByAgent(agentId) {
+        return this.episodes.filter((ep) => ep.agentId === agentId);
+    }
+    getBySession(sessionId) {
+        return this.episodes.filter((ep) => ep.sessionId === sessionId);
+    }
+    getByTimeRange(start, end) {
+        return this.episodes.filter((ep) => ep.timestamp >= start && ep.timestamp <= end);
+    }
+    getRecent(count) {
+        return this.episodes.slice(-count);
+    }
+    getWorkSummary() {
+        const eps = this.episodes;
+        // Agent breakdown
+        const agentMap = new Map();
+        for (const ep of eps) {
+            const entry = agentMap.get(ep.agentId) ?? { count: 0, maxEffort: 'trivial', timeMs: 0 };
+            entry.count++;
+            if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(entry.maxEffort)) {
+                entry.maxEffort = ep.effort;
+            }
+            entry.timeMs += ep.durationMs ?? 0;
+            agentMap.set(ep.agentId, entry);
+        }
+        // Top files
+        const fileCount = new Map();
+        for (const ep of eps) {
+            for (const f of ep.files) {
+                fileCount.set(f, (fileCount.get(f) ?? 0) + 1);
+            }
+        }
+        const topFiles = [...fileCount.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([p, touchCount]) => ({ path: p, touchCount }));
+        // Uncommitted work: episodes after last git_commit episode
+        let lastCommitIdx = -1;
+        for (let i = eps.length - 1; i >= 0; i--) {
+            if (eps[i].action === 'commit') {
+                lastCommitIdx = i;
+                break;
+            }
+        }
+        const uncommittedWork = lastCommitIdx >= 0 ? eps.slice(lastCommitIdx + 1) : [...eps];
+        return {
+            episodeCount: eps.length,
+            totalEffort: this.getTotalEffort(eps),
+            timeSpentMs: eps.reduce((sum, ep) => sum + (ep.durationMs ?? 0), 0),
+            agentBreakdown: [...agentMap.entries()].map(([agentId, entry]) => ({
+                agentId,
+                episodeCount: entry.count,
+                maxEffort: entry.maxEffort,
+                timeSpentMs: entry.timeMs,
+            })),
+            topFiles,
+            uncommittedWork,
+        };
+    }
+    getTotalEffort(episodes) {
+        const eps = episodes ?? this.episodes;
+        if (eps.length === 0)
+            return 'trivial';
+        return maxEffort(eps);
+    }
+    // ---------------------------------------------------------------------------
+    // Cleanup
+    // ---------------------------------------------------------------------------
+    cleanup(maxAgeMs) {
+        const cutoff = new Date(Date.now() - (maxAgeMs ?? this.maxAgeMs)).toISOString();
+        const before = this.episodes.length;
+        this._episodes = this.episodes.filter((ep) => ep.timestamp > cutoff);
+        const removed = before - this._episodes.length;
+        if (removed > 0) {
+            void this.flush();
+        }
+        return removed;
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    loadFromDisk() {
+        try {
+            if (!fs.existsSync(this.filePath))
+                return [];
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime data from disk, version may differ
+            if (data.version === 1 && Array.isArray(data.episodes)) {
+                return data.episodes;
+            }
+            return [];
+        }
+        catch {
+            // Corrupted file — start fresh
+            return [];
+        }
+    }
+    async flush() {
+        // Coalesce concurrent flushes
+        if (this.flushPromise)
+            return this.flushPromise;
+        this.flushPromise = (async () => {
+            try {
+                const dir = path.dirname(this.filePath);
+                await fs.promises.mkdir(dir, { recursive: true });
+                // Prune to max episodes (keep most recent)
+                const eps = this.episodes;
+                const prunedEpisodes = eps.length > this.maxEpisodes ? eps.slice(-this.maxEpisodes) : eps;
+                if (prunedEpisodes !== eps) {
+                    this._episodes = prunedEpisodes;
+                }
+                const data = {
+                    version: 1,
+                    episodes: prunedEpisodes,
+                    lastCleanup: new Date().toISOString(),
+                };
+                await fs.promises.writeFile(this.filePath, JSON.stringify(data, null, 2), 'utf-8');
+            }
+            catch {
+                // Silently fail — episodes are best-effort, never crash the CLI
+            }
+            finally {
+                this.flushPromise = null;
+            }
+        })();
+        return this.flushPromise;
+    }
+}
+// =============================================================================
+// Helpers (module-private)
+// =============================================================================
+function maxEffort(episodes) {
+    let max = 'trivial';
+    for (const ep of episodes) {
+        if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(max)) {
+            max = ep.effort;
+        }
+    }
+    return max;
+}

package/dist/episodes/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Episodic Memory Types (CLI)
+ *
+ * Re-exports core types from @compilr-dev/agents and adds CLI-internal types.
+ */
+export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, WorkAtRisk, EpisodeStore, } from '@compilr-dev/agents';
+/**
+ * Pending tool signal — accumulated during a batch window before
+ * being rolled into a WorkEpisode.
+ */
+export interface PendingToolSignal {
+    /** Tool name that was invoked */
+    toolName: string;
+    /** Files affected by this tool call */
+    files: string[];
+    /** Lines changed, if known */
+    linesChanged: number;
+    /** Duration of the tool call in milliseconds */
+    durationMs: number;
+    /** Whether the tool call succeeded */
+    success: boolean;
+    /** ISO timestamp of the tool call */
+    timestamp: string;
+}
+/**
+ * On-disk format for the episodes JSON file.
+ */
+export interface EpisodeFile {
+    /** File format version */
+    version: 1;
+    /** All stored episodes */
+    episodes: import('@compilr-dev/agents').WorkEpisode[];
+    /** ISO timestamp of last cleanup */
+    lastCleanup: string;
+}

package/dist/episodes/types.js

@@ -0,0 +1,6 @@
+/**
+ * Episodic Memory Types (CLI)
+ *
+ * Re-exports core types from @compilr-dev/agents and adds CLI-internal types.
+ */
+export {};

package/dist/episodes/work-at-risk.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Work At Risk Query
+ *
+ * Pure function to query episodes by affected files and build a WorkAtRisk summary.
+ * Used by guardrails and rehearsal to warn about destructive operations.
+ */
+import type { EpisodeStore, WorkAtRisk } from '@compilr-dev/agents';
+/**
+ * Query episodes that touch any of the given files and build a WorkAtRisk summary.
+ * Returns null if no episodes are at risk.
+ */
+export declare function queryWorkAtRisk(store: EpisodeStore, files: string[]): WorkAtRisk | null;

package/dist/episodes/work-at-risk.js

@@ -0,0 +1,38 @@
+/**
+ * Work At Risk Query
+ *
+ * Pure function to query episodes by affected files and build a WorkAtRisk summary.
+ * Used by guardrails and rehearsal to warn about destructive operations.
+ */
+import { EFFORT_ORDER } from '@compilr-dev/agents';
+/**
+ * Query episodes that touch any of the given files and build a WorkAtRisk summary.
+ * Returns null if no episodes are at risk.
+ */
+export function queryWorkAtRisk(store, files) {
+    const episodes = store.getByFiles(files);
+    if (episodes.length === 0)
+        return null;
+    // Max effort
+    let totalEffort = 'trivial';
+    for (const ep of episodes) {
+        if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(totalEffort)) {
+            totalEffort = ep.effort;
+        }
+    }
+    // Agent attribution: "agentId (terminalPrefix)"
+    const seen = new Set();
+    const agentAttribution = [];
+    for (const ep of episodes) {
+        const key = `${ep.agentId} (${ep.terminalPrefix})`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            agentAttribution.push(key);
+        }
+    }
+    // Warning message
+    const fileCount = new Set(episodes.flatMap(ep => ep.files)).size;
+    const warningMessage = `⚠️ ${String(episodes.length)} episode(s) of work (effort: ${totalEffort}) ` +
+        `on ${String(fileCount)} file(s) by ${agentAttribution.join(', ')} would be affected.`;
+    return { episodes, totalEffort, agentAttribution, warningMessage };
+}

package/dist/episodes/work-summary-anchor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Work Summary Anchor
+ *
+ * Manages an auto-generated anchor that summarizes work done in the current session.
+ * Updated automatically after each episode batch is flushed.
+ */
+import type { EpisodeStore, ProjectWorkSummary } from '@compilr-dev/agents';
+import type { AnchorManager } from '@compilr-dev/sdk';
+export interface WorkSummaryAnchorConfig {
+    store: EpisodeStore;
+    projectId: string;
+    getAnchorManager: (projectId: string) => AnchorManager;
+}
+/**
+ * Build the anchor content string from the store's work summary.
+ * Returns null when there are no episodes to summarize.
+ */
+export declare function buildWorkSummaryContent(summary: ProjectWorkSummary): string | null;
+/**
+ * Update the work summary anchor for a project.
+ * Removes existing anchor (if any) and adds updated one.
+ */
+export declare function updateWorkSummaryAnchor(config: WorkSummaryAnchorConfig): void;

package/dist/episodes/work-summary-anchor.js

@@ -0,0 +1,73 @@
+/**
+ * Work Summary Anchor
+ *
+ * Manages an auto-generated anchor that summarizes work done in the current session.
+ * Updated automatically after each episode batch is flushed.
+ */
+const ANCHOR_TAG = 'episode-work-summary';
+/**
+ * Build the anchor content string from the store's work summary.
+ * Returns null when there are no episodes to summarize.
+ */
+export function buildWorkSummaryContent(summary) {
+    if (summary.episodeCount === 0)
+        return null;
+    const lines = ['[Session Work Summary]'];
+    lines.push(`Episodes: ${String(summary.episodeCount)}, Effort: ${summary.totalEffort}, Time: ${formatMs(summary.timeSpentMs)}`);
+    if (summary.agentBreakdown.length > 0) {
+        const agents = summary.agentBreakdown
+            .map(a => `${a.agentId}(${String(a.episodeCount)})`)
+            .join(', ');
+        lines.push(`Agents: ${agents}`);
+    }
+    if (summary.topFiles.length > 0) {
+        const files = summary.topFiles.slice(0, 5)
+            .map(f => f.path.split('/').pop() ?? f.path)
+            .join(', ');
+        lines.push(`Top files: ${files}`);
+    }
+    if (summary.uncommittedWork.length > 0) {
+        lines.push(`Uncommitted: ${String(summary.uncommittedWork.length)} episode(s)`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Update the work summary anchor for a project.
+ * Removes existing anchor (if any) and adds updated one.
+ */
+export function updateWorkSummaryAnchor(config) {
+    const { store, projectId, getAnchorManager: getManager } = config;
+    const manager = getManager(projectId);
+    const summary = store.getWorkSummary();
+    const content = buildWorkSummaryContent(summary);
+    // Remove existing work summary anchor
+    const existing = manager.getAll().find((a) => a.tags?.includes(ANCHOR_TAG));
+    if (existing)
+        manager.remove(existing.id);
+    // Add new anchor if there's content
+    if (content) {
+        manager.add({
+            content,
+            priority: 'info',
+            scope: 'persistent',
+            tags: [ANCHOR_TAG],
+            projectId,
+        });
+    }
+}
+/**
+ * Format milliseconds to a human-readable string (e.g., "2h 15m", "45s").
+ */
+function formatMs(ms) {
+    if (ms < 1000)
+        return `${String(ms)}ms`;
+    const totalSeconds = Math.floor(ms / 1000);
+    if (totalSeconds < 60)
+        return `${String(totalSeconds)}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60)
+        return `${String(minutes)}m`;
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return remainingMinutes > 0 ? `${String(hours)}h ${String(remainingMinutes)}m` : `${String(hours)}h`;
+}

package/dist/games/coins.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Coin System
+ *
+ * Manages arcade coins for the games easter egg.
+ * Coins are earned through productive CLI usage and spent to play games.
+ */
+export interface CoinData {
+    coins: number;
+    totalEarned: number;
+    totalSpent: number;
+    lastDailyBonus: string | null;
+}
+export declare const COIN_COST_START_GAME = 1;
+export declare const COIN_COST_CONTINUE = 2;
+export declare const COIN_REWARD_WORK_ITEM = 1;
+export declare const COIN_REWARD_FIRST_PROJECT = 3;
+export declare const COIN_REWARD_DAILY_BONUS = 1;
+export declare const COIN_REWARD_HIGH_SCORE = 2;
+/**
+ * Get current coin data
+ */
+export declare function getCoinData(): CoinData;
+/**
+ * Get current coin balance
+ */
+export declare function getCoins(): number;
+/**
+ * Check if player has enough coins
+ */
+export declare function hasCoins(amount: number): boolean;
+/**
+ * Spend coins (returns true if successful)
+ */
+export declare function spendCoins(amount: number): boolean;
+/**
+ * Earn coins
+ */
+export declare function earnCoins(amount: number, reason?: string): void;
+/**
+ * Check and award daily bonus if eligible
+ */
+export declare function checkDailyBonus(): boolean;
+/**
+ * Award coins for completing a work item
+ */
+export declare function awardWorkItemCompletion(): void;
+/**
+ * Award coins for creating first project
+ */
+export declare function awardFirstProject(): void;
+/**
+ * Award coins for achieving a high score
+ */
+export declare function awardHighScore(): void;
+/**
+ * Clear cache (for testing)
+ */
+export declare function clearCoinCache(): void;
+/**
+ * Format coins for display (e.g., "●●●○○" for 3/5)
+ */
+export declare function formatCoinsDisplay(current: number, max?: number): string;
+/**
+ * Get a short coin display string
+ */
+export declare function getCoinsDisplayShort(): string;

package/dist/games/coins.js

@@ -0,0 +1,165 @@
+/**
+ * Coin System
+ *
+ * Manages arcade coins for the games easter egg.
+ * Coins are earned through productive CLI usage and spent to play games.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// =============================================================================
+// Constants
+// =============================================================================
+const CONFIG_DIR = path.join(os.homedir(), '.compilr-dev');
+const GAMES_FILE = path.join(CONFIG_DIR, 'games.json');
+const DEFAULT_COIN_DATA = {
+    coins: 3, // Start with 3 free coins!
+    totalEarned: 3,
+    totalSpent: 0,
+    lastDailyBonus: null,
+};
+// Coin costs
+export const COIN_COST_START_GAME = 1;
+export const COIN_COST_CONTINUE = 2;
+// Coin rewards
+export const COIN_REWARD_WORK_ITEM = 1;
+export const COIN_REWARD_FIRST_PROJECT = 3;
+export const COIN_REWARD_DAILY_BONUS = 1;
+export const COIN_REWARD_HIGH_SCORE = 2;
+// =============================================================================
+// In-memory cache
+// =============================================================================
+let coinCache = null;
+// =============================================================================
+// Persistence
+// =============================================================================
+function loadFromDisk() {
+    try {
+        if (fs.existsSync(GAMES_FILE)) {
+            const data = fs.readFileSync(GAMES_FILE, 'utf-8');
+            const parsed = JSON.parse(data);
+            return { ...DEFAULT_COIN_DATA, ...parsed };
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return { ...DEFAULT_COIN_DATA };
+}
+function saveToDisk(data) {
+    try {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        fs.writeFileSync(GAMES_FILE, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch (error) {
+        console.error('Failed to save coin data:', error);
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Get current coin data
+ */
+export function getCoinData() {
+    if (coinCache) {
+        return coinCache;
+    }
+    coinCache = loadFromDisk();
+    return coinCache;
+}
+/**
+ * Get current coin balance
+ */
+export function getCoins() {
+    return getCoinData().coins;
+}
+/**
+ * Check if player has enough coins
+ */
+export function hasCoins(amount) {
+    return getCoins() >= amount;
+}
+/**
+ * Spend coins (returns true if successful)
+ */
+export function spendCoins(amount) {
+    const data = getCoinData();
+    if (data.coins < amount) {
+        return false;
+    }
+    data.coins -= amount;
+    data.totalSpent += amount;
+    coinCache = data;
+    saveToDisk(data);
+    return true;
+}
+/**
+ * Earn coins
+ */
+export function earnCoins(amount, reason) {
+    const data = getCoinData();
+    data.coins += amount;
+    data.totalEarned += amount;
+    coinCache = data;
+    saveToDisk(data);
+    // Log for debugging (could be made optional)
+    if (reason) {
+        // Silent for now - could add notification later
+    }
+}
+/**
+ * Check and award daily bonus if eligible
+ */
+export function checkDailyBonus() {
+    const data = getCoinData();
+    const today = new Date().toISOString().split('T')[0];
+    if (data.lastDailyBonus !== today) {
+        data.lastDailyBonus = today;
+        data.coins += COIN_REWARD_DAILY_BONUS;
+        data.totalEarned += COIN_REWARD_DAILY_BONUS;
+        coinCache = data;
+        saveToDisk(data);
+        return true;
+    }
+    return false;
+}
+/**
+ * Award coins for completing a work item
+ */
+export function awardWorkItemCompletion() {
+    earnCoins(COIN_REWARD_WORK_ITEM, 'work_item_completed');
+}
+/**
+ * Award coins for creating first project
+ */
+export function awardFirstProject() {
+    earnCoins(COIN_REWARD_FIRST_PROJECT, 'first_project');
+}
+/**
+ * Award coins for achieving a high score
+ */
+export function awardHighScore() {
+    earnCoins(COIN_REWARD_HIGH_SCORE, 'high_score');
+}
+/**
+ * Clear cache (for testing)
+ */
+export function clearCoinCache() {
+    coinCache = null;
+}
+/**
+ * Format coins for display (e.g., "●●●○○" for 3/5)
+ */
+export function formatCoinsDisplay(current, max = 10) {
+    const filled = Math.min(current, max);
+    const empty = Math.max(0, max - filled);
+    return '●'.repeat(filled) + '○'.repeat(empty);
+}
+/**
+ * Get a short coin display string
+ */
+export function getCoinsDisplayShort() {
+    const coins = getCoins();
+    return `${String(coins)} coin${coins !== 1 ? 's' : ''}`;
+}