@skillsmith/core 0.1.0

package/dist/src/analytics/metrics-aggregator.js

@@ -0,0 +1,176 @@
+/**
+ * SMI-915: Metrics Aggregator
+ *
+ * Aggregates skill usage events into actionable metrics for value measurement.
+ * Provides:
+ * - Per-skill metrics aggregation
+ * - Global metrics across all skills
+ * - Retention rate calculation
+ * - Time-period filtering
+ */
+/**
+ * Aggregates skill usage metrics from the database
+ */
+export class MetricsAggregator {
+    db;
+    /**
+     * Create a metrics aggregator
+     *
+     * @param db - SQLite database instance
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Get metrics for a specific skill
+     *
+     * @param skillId - The skill identifier
+     * @param period - Optional time period filter
+     * @returns Aggregated metrics for the skill
+     */
+    getSkillMetrics(skillId, period) {
+        const whereClause = period
+            ? 'WHERE skill_id = ? AND timestamp >= ? AND timestamp <= ?'
+            : 'WHERE skill_id = ?';
+        const params = period ? [skillId, period.start, period.end] : [skillId];
+        const stats = this.db
+            .prepare(`
+      SELECT
+        COUNT(*) as total,
+        SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) as successes,
+        AVG(task_duration) as avg_duration,
+        COUNT(DISTINCT user_id) as unique_users,
+        MAX(timestamp) as last_used
+      FROM usage_events
+      ${whereClause}
+    `)
+            .get(...params);
+        return {
+            skillId,
+            totalInvocations: stats?.total || 0,
+            successRate: stats && stats.total > 0 ? stats.successes / stats.total : 0,
+            avgTaskDuration: Math.round(stats?.avg_duration || 0),
+            uniqueUsers: stats?.unique_users || 0,
+            lastUsed: stats?.last_used || 0,
+        };
+    }
+    /**
+     * Get metrics for all skills
+     *
+     * @param period - Optional time period filter
+     * @returns Array of metrics for each skill
+     */
+    getAllSkillMetrics(period) {
+        const whereClause = period ? 'WHERE timestamp >= ? AND timestamp <= ?' : '';
+        const params = period ? [period.start, period.end] : [];
+        const skillIds = this.db
+            .prepare(`SELECT DISTINCT skill_id FROM usage_events ${whereClause}`)
+            .all(...params);
+        return skillIds.map(({ skill_id }) => this.getSkillMetrics(skill_id, period));
+    }
+    /**
+     * Get global metrics across all skills
+     *
+     * @param period - Optional time period filter
+     * @returns Aggregated metrics for all skills
+     */
+    getGlobalMetrics(period) {
+        const whereClause = period ? 'WHERE timestamp >= ? AND timestamp <= ?' : '';
+        const params = period ? [period.start, period.end] : [];
+        const stats = this.db
+            .prepare(`
+      SELECT
+        COUNT(*) as total,
+        SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) as successes,
+        AVG(task_duration) as avg_duration,
+        COUNT(DISTINCT user_id) as unique_users
+      FROM usage_events
+      ${whereClause}
+    `)
+            .get(...params);
+        const topSkills = this.db
+            .prepare(`
+      SELECT skill_id, COUNT(*) as invocations
+      FROM usage_events
+      ${whereClause}
+      GROUP BY skill_id
+      ORDER BY invocations DESC
+      LIMIT 10
+    `)
+            .all(...params);
+        return {
+            totalInvocations: stats?.total || 0,
+            uniqueUsers: stats?.unique_users || 0,
+            overallSuccessRate: stats && stats.total > 0 ? stats.successes / stats.total : 0,
+            avgTaskDuration: Math.round(stats?.avg_duration || 0),
+            topSkills: topSkills.map((s) => ({ skillId: s.skill_id, invocations: s.invocations })),
+        };
+    }
+    /**
+     * Calculate retention rate (users who used skill again within N days)
+     *
+     * @param skillId - The skill identifier
+     * @param days - Retention window in days (default: 7)
+     * @returns Retention rate (0-1)
+     */
+    getRetentionRate(skillId, days = 7) {
+        const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+        // Get users who used the skill before cutoff
+        const earlyUsers = this.db
+            .prepare(`
+      SELECT DISTINCT user_id FROM usage_events
+      WHERE skill_id = ? AND timestamp < ?
+    `)
+            .all(skillId, cutoff);
+        if (earlyUsers.length === 0)
+            return 0;
+        // Build parameterized query for returned users
+        const placeholders = earlyUsers.map(() => '?').join(',');
+        const userIds = earlyUsers.map((u) => u.user_id);
+        // Count how many returned after cutoff
+        const returnedUsers = this.db
+            .prepare(`
+      SELECT COUNT(DISTINCT user_id) as count FROM usage_events
+      WHERE skill_id = ? AND timestamp >= ? AND user_id IN (${placeholders})
+    `)
+            .get(skillId, cutoff, ...userIds);
+        return returnedUsers.count / earlyUsers.length;
+    }
+    /**
+     * Get skills with usage in the specified period
+     *
+     * @param period - Time period filter
+     * @returns Array of skill IDs with usage
+     */
+    getActiveSkills(period) {
+        const skillIds = this.db
+            .prepare(`
+      SELECT DISTINCT skill_id FROM usage_events
+      WHERE timestamp >= ? AND timestamp <= ?
+      ORDER BY skill_id
+    `)
+            .all(period.start, period.end);
+        return skillIds.map((row) => row.skill_id);
+    }
+    /**
+     * Get the date range of available data
+     *
+     * @returns Object with min and max timestamps, or null if no data
+     */
+    getDataRange() {
+        const result = this.db
+            .prepare(`
+      SELECT MIN(timestamp) as min_ts, MAX(timestamp) as max_ts
+      FROM usage_events
+    `)
+            .get();
+        if (result.min_ts === null || result.max_ts === null) {
+            return null;
+        }
+        return {
+            minTimestamp: result.min_ts,
+            maxTimestamp: result.max_ts,
+        };
+    }
+}
+//# sourceMappingURL=metrics-aggregator.js.map

package/dist/src/analytics/metrics-aggregator.js.map

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

package/dist/src/analytics/metrics-exporter.d.ts

@@ -0,0 +1,148 @@
+/**
+ * SMI-915: Metrics Exporter
+ *
+ * Exports aggregated metrics to various formats for analysis and reporting.
+ * Supports:
+ * - JSON export with full metrics data
+ * - CSV export for spreadsheet analysis
+ * - Weekly/daily/custom period exports
+ * - Retention metrics (optional)
+ */
+/**
+ * Validates that a path does not escape the allowed base directory.
+ * Prevents path traversal attacks using sequences like '../'.
+ *
+ * @param inputPath - The path to validate (can be relative or absolute)
+ * @param baseDir - The allowed base directory
+ * @returns The resolved, sanitized absolute path
+ * @throws Error if the path attempts to escape the base directory
+ */
+export declare function validatePath(inputPath: string, baseDir: string): string;
+import type { MetricsAggregator, GlobalMetrics, AggregationPeriod } from './metrics-aggregator.js';
+import type { SkillMetrics } from './types.js';
+/**
+ * Exported metrics structure
+ */
+export interface MetricsExport {
+    /** ISO timestamp when export was generated */
+    exportedAt: string;
+    /** Period information */
+    period: {
+        /** ISO timestamp of period start */
+        start: string;
+        /** ISO timestamp of period end */
+        end: string;
+        /** Human-readable label (e.g., "2026-W01") */
+        label: string;
+    };
+    /** Global metrics across all skills */
+    global: GlobalMetrics;
+    /** Per-skill metrics keyed by skill ID */
+    skills: Record<string, SkillMetrics>;
+    /** Optional retention data by skill */
+    retention?: Record<string, number>;
+}
+/**
+ * Export configuration options
+ */
+export interface ExportOptions {
+    /** Directory for output files (defaults to ~/.skillsmith/exports) */
+    outputDir?: string;
+    /** Output format (defaults to 'json') */
+    format?: 'json' | 'csv';
+    /** Include retention rate calculations (defaults to false) */
+    includeRetention?: boolean;
+    /** Retention period in days for calculation (defaults to 7) */
+    retentionDays?: number;
+}
+/**
+ * Exports metrics to files in various formats
+ */
+export declare class MetricsExporter {
+    private aggregator;
+    /**
+     * Create a metrics exporter
+     *
+     * @param aggregator - MetricsAggregator instance
+     */
+    constructor(aggregator: MetricsAggregator);
+    /**
+     * Get ISO week label (e.g., "2026-W01")
+     *
+     * @param date - Date to get week label for
+     * @returns ISO week label string
+     */
+    private getWeekLabel;
+    /**
+     * Get day label (e.g., "2026-01-01")
+     *
+     * @param date - Date to get label for
+     * @returns ISO date string (YYYY-MM-DD)
+     */
+    private getDayLabel;
+    /**
+     * Export metrics for the last N days
+     *
+     * @param days - Number of days to include
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    exportLastNDays(days: number, options?: ExportOptions): MetricsExport;
+    /**
+     * Export metrics for a specific week
+     *
+     * @param date - Any date within the desired week (defaults to current week)
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    exportWeek(date?: Date, options?: ExportOptions): MetricsExport;
+    /**
+     * Export metrics for a specific day
+     *
+     * @param date - The date to export (defaults to today)
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    exportDay(date?: Date, options?: ExportOptions): MetricsExport;
+    /**
+     * Export metrics for a time period
+     *
+     * @param period - Aggregation period
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    export(period: AggregationPeriod, options?: ExportOptions): MetricsExport;
+    /**
+     * Save export data to a file
+     *
+     * @param data - Metrics export data
+     * @param options - Export options
+     * @param allowedBaseDir - Optional base directory to restrict path access (defaults to DEFAULT_EXPORT_DIR)
+     * @returns Path to the saved file
+     * @throws Error if outputDir attempts to escape the allowedBaseDir
+     */
+    saveToFile(data: MetricsExport, options?: ExportOptions, allowedBaseDir?: string): string;
+    /**
+     * Convert export data to CSV format
+     *
+     * @param data - Metrics export data
+     * @returns CSV string
+     */
+    private toCSV;
+    /**
+     * Escape a string for CSV output
+     *
+     * @param value - String to escape
+     * @returns Escaped string
+     */
+    private escapeCSV;
+    /**
+     * Export to JSON string (for programmatic use)
+     *
+     * @param data - Metrics export data
+     * @param pretty - Whether to format with indentation (defaults to true)
+     * @returns JSON string
+     */
+    toJSON(data: MetricsExport, pretty?: boolean): string;
+}
+//# sourceMappingURL=metrics-exporter.d.ts.map

package/dist/src/analytics/metrics-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-exporter.d.ts","sourceRoot":"","sources":["../../../src/analytics/metrics-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWvE;AACD,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAClG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,yBAAyB;IACzB,MAAM,EAAE;QACN,oCAAoC;QACpC,KAAK,EAAE,MAAM,CAAA;QACb,kCAAkC;QAClC,GAAG,EAAE,MAAM,CAAA;QACX,8CAA8C;QAC9C,KAAK,EAAE,MAAM,CAAA;KACd,CAAA;IACD,uCAAuC;IACvC,MAAM,EAAE,aAAa,CAAA;IACrB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACpC,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACvB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAOD;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,UAAU,CAAmB;IAErC;;;;OAIG;gBACS,UAAU,EAAE,iBAAiB;IAIzC;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,aAAa;IAQzE;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,GAAE,IAAiB,EAAE,OAAO,GAAE,aAAkB,GAAG,aAAa;IAe/E;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,GAAE,IAAiB,EAAE,OAAO,GAAE,aAAkB,GAAG,aAAa;IAU9E;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,aAAkB,GAAG,aAAa;IAmC7E;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,aAAkB,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM;IAyB7F;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAsCb;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAOjB;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM;CAG5D"}

package/dist/src/analytics/metrics-exporter.js

@@ -0,0 +1,244 @@
+/**
+ * SMI-915: Metrics Exporter
+ *
+ * Exports aggregated metrics to various formats for analysis and reporting.
+ * Supports:
+ * - JSON export with full metrics data
+ * - CSV export for spreadsheet analysis
+ * - Weekly/daily/custom period exports
+ * - Retention metrics (optional)
+ */
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, resolve, isAbsolute } from 'path';
+import { homedir } from 'os';
+/**
+ * Validates that a path does not escape the allowed base directory.
+ * Prevents path traversal attacks using sequences like '../'.
+ *
+ * @param inputPath - The path to validate (can be relative or absolute)
+ * @param baseDir - The allowed base directory
+ * @returns The resolved, sanitized absolute path
+ * @throws Error if the path attempts to escape the base directory
+ */
+export function validatePath(inputPath, baseDir) {
+    const resolvedBase = resolve(baseDir);
+    const resolvedPath = isAbsolute(inputPath) ? resolve(inputPath) : resolve(baseDir, inputPath);
+    // Ensure the resolved path starts with the base directory
+    // Add path separator to prevent partial matches (e.g., /base vs /base-other)
+    if (!resolvedPath.startsWith(resolvedBase + '/') && resolvedPath !== resolvedBase) {
+        throw new Error(`Path traversal attempt detected: ${inputPath}`);
+    }
+    return resolvedPath;
+}
+/**
+ * Default export directory
+ */
+const DEFAULT_EXPORT_DIR = join(homedir(), '.skillsmith', 'exports');
+/**
+ * Exports metrics to files in various formats
+ */
+export class MetricsExporter {
+    aggregator;
+    /**
+     * Create a metrics exporter
+     *
+     * @param aggregator - MetricsAggregator instance
+     */
+    constructor(aggregator) {
+        this.aggregator = aggregator;
+    }
+    /**
+     * Get ISO week label (e.g., "2026-W01")
+     *
+     * @param date - Date to get week label for
+     * @returns ISO week label string
+     */
+    getWeekLabel(date) {
+        const year = date.getFullYear();
+        const oneJan = new Date(year, 0, 1);
+        const days = Math.floor((date.getTime() - oneJan.getTime()) / (24 * 60 * 60 * 1000));
+        const weekNum = Math.ceil((days + oneJan.getDay() + 1) / 7);
+        return `${year}-W${weekNum.toString().padStart(2, '0')}`;
+    }
+    /**
+     * Get day label (e.g., "2026-01-01")
+     *
+     * @param date - Date to get label for
+     * @returns ISO date string (YYYY-MM-DD)
+     */
+    getDayLabel(date) {
+        return date.toISOString().split('T')[0];
+    }
+    /**
+     * Export metrics for the last N days
+     *
+     * @param days - Number of days to include
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    exportLastNDays(days, options = {}) {
+        const end = Date.now();
+        const start = end - days * 24 * 60 * 60 * 1000;
+        const period = { start, end };
+        return this.export(period, options);
+    }
+    /**
+     * Export metrics for a specific week
+     *
+     * @param date - Any date within the desired week (defaults to current week)
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    exportWeek(date = new Date(), options = {}) {
+        // Get start of week (Monday)
+        const d = new Date(date);
+        const day = d.getDay();
+        const diff = d.getDate() - day + (day === 0 ? -6 : 1);
+        const start = new Date(d.setDate(diff));
+        start.setHours(0, 0, 0, 0);
+        const end = new Date(start);
+        end.setDate(end.getDate() + 7);
+        const period = { start: start.getTime(), end: end.getTime() };
+        return this.export(period, options);
+    }
+    /**
+     * Export metrics for a specific day
+     *
+     * @param date - The date to export (defaults to today)
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    exportDay(date = new Date(), options = {}) {
+        const d = new Date(date);
+        d.setHours(0, 0, 0, 0);
+        const start = d.getTime();
+        const end = start + 24 * 60 * 60 * 1000;
+        const period = { start, end };
+        return this.export(period, options);
+    }
+    /**
+     * Export metrics for a time period
+     *
+     * @param period - Aggregation period
+     * @param options - Export options
+     * @returns Exported metrics data
+     */
+    export(period, options = {}) {
+        const global = this.aggregator.getGlobalMetrics(period);
+        const skillMetrics = this.aggregator.getAllSkillMetrics(period);
+        const skills = {};
+        for (const metric of skillMetrics) {
+            skills[metric.skillId] = metric;
+        }
+        const exportData = {
+            exportedAt: new Date().toISOString(),
+            period: {
+                start: new Date(period.start).toISOString(),
+                end: new Date(period.end).toISOString(),
+                label: this.getWeekLabel(new Date(period.start)),
+            },
+            global,
+            skills,
+        };
+        // Optionally include retention data
+        if (options.includeRetention) {
+            const retentionDays = options.retentionDays ?? 7;
+            const retention = {};
+            for (const skillId of Object.keys(skills)) {
+                retention[skillId] = this.aggregator.getRetentionRate(skillId, retentionDays);
+            }
+            exportData.retention = retention;
+        }
+        return exportData;
+    }
+    /**
+     * Save export data to a file
+     *
+     * @param data - Metrics export data
+     * @param options - Export options
+     * @param allowedBaseDir - Optional base directory to restrict path access (defaults to DEFAULT_EXPORT_DIR)
+     * @returns Path to the saved file
+     * @throws Error if outputDir attempts to escape the allowedBaseDir
+     */
+    saveToFile(data, options = {}, allowedBaseDir) {
+        const outputDir = options.outputDir || DEFAULT_EXPORT_DIR;
+        const format = options.format || 'json';
+        // Validate output directory to prevent path traversal attacks
+        const baseDir = allowedBaseDir ?? DEFAULT_EXPORT_DIR;
+        const validatedOutputDir = validatePath(outputDir, baseDir);
+        if (!existsSync(validatedOutputDir)) {
+            mkdirSync(validatedOutputDir, { recursive: true });
+        }
+        const filename = `metrics-${data.period.label}.${format}`;
+        const filepath = join(validatedOutputDir, filename);
+        if (format === 'json') {
+            writeFileSync(filepath, JSON.stringify(data, null, 2));
+        }
+        else if (format === 'csv') {
+            const csv = this.toCSV(data);
+            writeFileSync(filepath, csv);
+        }
+        return filepath;
+    }
+    /**
+     * Convert export data to CSV format
+     *
+     * @param data - Metrics export data
+     * @returns CSV string
+     */
+    toCSV(data) {
+        const lines = [];
+        // Header with optional retention column
+        const headers = [
+            'skill_id',
+            'total_invocations',
+            'success_rate',
+            'avg_duration_ms',
+            'unique_users',
+            'last_used',
+        ];
+        if (data.retention) {
+            headers.push('retention_rate');
+        }
+        lines.push(headers.join(','));
+        // Data rows
+        for (const [skillId, metrics] of Object.entries(data.skills)) {
+            const row = [
+                this.escapeCSV(skillId),
+                metrics.totalInvocations.toString(),
+                metrics.successRate.toFixed(3),
+                metrics.avgTaskDuration.toString(),
+                metrics.uniqueUsers.toString(),
+                metrics.lastUsed > 0 ? new Date(metrics.lastUsed).toISOString() : '',
+            ];
+            if (data.retention) {
+                row.push((data.retention[skillId] ?? 0).toFixed(3));
+            }
+            lines.push(row.join(','));
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Escape a string for CSV output
+     *
+     * @param value - String to escape
+     * @returns Escaped string
+     */
+    escapeCSV(value) {
+        if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+            return `"${value.replace(/"/g, '""')}"`;
+        }
+        return value;
+    }
+    /**
+     * Export to JSON string (for programmatic use)
+     *
+     * @param data - Metrics export data
+     * @param pretty - Whether to format with indentation (defaults to true)
+     * @returns JSON string
+     */
+    toJSON(data, pretty = true) {
+        return pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+    }
+}
+//# sourceMappingURL=metrics-exporter.js.map

package/dist/src/analytics/metrics-exporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-exporter.js","sourceRoot":"","sources":["../../../src/analytics/metrics-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,IAAI,CAAA;AACzD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAA;AAE5B;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,OAAe;IAC7D,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;IAE7F,0DAA0D;IAC1D,6EAA6E;IAC7E,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,GAAG,GAAG,CAAC,IAAI,YAAY,KAAK,YAAY,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,OAAO,YAAY,CAAA;AACrB,CAAC;AAyCD;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,CAAC,CAAA;AAEpE;;GAEG;AACH,MAAM,OAAO,eAAe;IAClB,UAAU,CAAmB;IAErC;;;;OAIG;IACH,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;IAED;;;;;OAKG;IACK,YAAY,CAAC,IAAU;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QAC/B,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAA;QACpF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QAC3D,OAAO,GAAG,IAAI,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;IAC1D,CAAC;IAED;;;;;OAKG;IACK,WAAW,CAAC,IAAU;QAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,CAAC;IAED;;;;;;OAMG;IACH,eAAe,CAAC,IAAY,EAAE,UAAyB,EAAE;QACvD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;QAC9C,MAAM,MAAM,GAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;QAEhD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,OAAa,IAAI,IAAI,EAAE,EAAE,UAAyB,EAAE;QAC7D,6BAA6B;QAC7B,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;QACxB,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,CAAA;QACtB,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACrD,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;QACvC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QAE1B,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAA;QAE9B,MAAM,MAAM,GAAsB,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,CAAA;QAChF,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,OAAa,IAAI,IAAI,EAAE,EAAE,UAAyB,EAAE;QAC5D,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;QACxB,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QACtB,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,CAAA;QACzB,MAAM,GAAG,GAAG,KAAK,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;QAEvC,MAAM,MAAM,GAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;QAChD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAyB,EAAE,UAAyB,EAAE;QAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAA;QACvD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;QAE/D,MAAM,MAAM,GAAiC,EAAE,CAAA;QAC/C,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;YAClC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAA;QACjC,CAAC;QAED,MAAM,UAAU,GAAkB;YAChC,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,MAAM,EAAE;gBACN,KAAK,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;gBAC3C,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE;gBACvC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aACjD;YACD,MAAM;YACN,MAAM;SACP,CAAA;QAED,oCAAoC;QACpC,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAC7B,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAA;YAChD,MAAM,SAAS,GAA2B,EAAE,CAAA;YAE5C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1C,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;YAC/E,CAAC;YAED,UAAU,CAAC,SAAS,GAAG,SAAS,CAAA;QAClC,CAAC;QAED,OAAO,UAAU,CAAA;IACnB,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAmB,EAAE,UAAyB,EAAE,EAAE,cAAuB;QAClF,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAA;QACzD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAA;QAEvC,8DAA8D;QAC9D,MAAM,OAAO,GAAG,cAAc,IAAI,kBAAkB,CAAA;QACpD,MAAM,kBAAkB,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAE3D,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACpC,SAAS,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACpD,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,EAAE,CAAA;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAA;QAEnD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QACxD,CAAC;aAAM,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAC5B,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;QAC9B,CAAC;QAED,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,IAAmB;QAC/B,MAAM,KAAK,GAAa,EAAE,CAAA;QAE1B,wCAAwC;QACxC,MAAM,OAAO,GAAG;YACd,UAAU;YACV,mBAAmB;YACnB,cAAc;YACd,iBAAiB;YACjB,cAAc;YACd,WAAW;SACZ,CAAA;QACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;QAChC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAE7B,YAAY;QACZ,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,MAAM,GAAG,GAAG;gBACV,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBACvB,OAAO,CAAC,gBAAgB,CAAC,QAAQ,EAAE;gBACnC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC9B,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE;gBAClC,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE;gBAC9B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE;aACrE,CAAA;YAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;YACrD,CAAC;YAED,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAC3B,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED;;;;;OAKG;IACK,SAAS,CAAC,KAAa;QAC7B,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAA;QACzC,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAmB,EAAE,SAAkB,IAAI;QAChD,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IACtE,CAAC;CACF"}

package/dist/src/analytics/schema.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Analytics Database Schema
+ *
+ * Implements Phase 4 Product Strategy analytics infrastructure:
+ * - Epic 3: Skill usage tracking with 30-day rolling window
+ * - Epic 4: A/B testing experiment management
+ * - Epic 4: ROI metrics and dashboard data
+ *
+ * SMI-XXX: Analytics infrastructure for product strategy
+ */
+/**
+ * Analytics schema SQL for skill usage, A/B testing, and ROI tracking
+ */
+export declare const ANALYTICS_SCHEMA = "\n-- Skill usage events for attribution and value tracking\nCREATE TABLE IF NOT EXISTS skill_usage_events (\n  id TEXT PRIMARY KEY,\n  skill_id TEXT NOT NULL,\n  user_id TEXT NOT NULL,\n  session_id TEXT NOT NULL,\n  event_type TEXT NOT NULL CHECK(event_type IN ('activation', 'invocation', 'success', 'failure')),\n  context TEXT, -- JSON metadata about the usage context\n  value_score REAL, -- Estimated value contribution (0-1)\n  timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Indexes for usage queries\nCREATE INDEX IF NOT EXISTS idx_usage_skill_id ON skill_usage_events(skill_id);\nCREATE INDEX IF NOT EXISTS idx_usage_user_id ON skill_usage_events(user_id);\nCREATE INDEX IF NOT EXISTS idx_usage_session_id ON skill_usage_events(session_id);\nCREATE INDEX IF NOT EXISTS idx_usage_timestamp ON skill_usage_events(timestamp);\nCREATE INDEX IF NOT EXISTS idx_usage_event_type ON skill_usage_events(event_type);\n\n-- A/B testing experiments\nCREATE TABLE IF NOT EXISTS experiments (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n  description TEXT,\n  hypothesis TEXT,\n  status TEXT NOT NULL CHECK(status IN ('draft', 'active', 'paused', 'completed')) DEFAULT 'draft',\n  variant_a TEXT NOT NULL, -- JSON config for control group\n  variant_b TEXT NOT NULL, -- JSON config for treatment group\n  start_date TEXT,\n  end_date TEXT,\n  target_sample_size INTEGER DEFAULT 100,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- User assignments to experiment variants\nCREATE TABLE IF NOT EXISTS experiment_assignments (\n  id TEXT PRIMARY KEY,\n  experiment_id TEXT NOT NULL REFERENCES experiments(id) ON DELETE CASCADE,\n  user_id TEXT NOT NULL,\n  variant TEXT NOT NULL CHECK(variant IN ('control', 'treatment')),\n  assigned_at TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(experiment_id, user_id)\n);\n\n-- Experiment outcome tracking\nCREATE TABLE IF NOT EXISTS experiment_outcomes (\n  id TEXT PRIMARY KEY,\n  experiment_id TEXT NOT NULL REFERENCES experiments(id) ON DELETE CASCADE,\n  assignment_id TEXT NOT NULL REFERENCES experiment_assignments(id) ON DELETE CASCADE,\n  outcome_type TEXT NOT NULL, -- e.g., 'activation', 'usage_count', 'value_score'\n  outcome_value REAL NOT NULL,\n  metadata TEXT, -- JSON additional data\n  measured_at TEXT NOT NULL DEFAULT (datetime('now')),\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Indexes for experiment queries\nCREATE INDEX IF NOT EXISTS idx_assignments_experiment ON experiment_assignments(experiment_id);\nCREATE INDEX IF NOT EXISTS idx_assignments_user ON experiment_assignments(user_id);\nCREATE INDEX IF NOT EXISTS idx_outcomes_experiment ON experiment_outcomes(experiment_id);\nCREATE INDEX IF NOT EXISTS idx_outcomes_assignment ON experiment_outcomes(assignment_id);\n\n-- ROI metrics aggregation (materialized view equivalent)\nCREATE TABLE IF NOT EXISTS roi_metrics (\n  id TEXT PRIMARY KEY,\n  metric_type TEXT NOT NULL, -- 'daily', 'weekly', 'monthly', 'user', 'skill'\n  entity_id TEXT, -- user_id or skill_id for entity-level metrics\n  period_start TEXT NOT NULL,\n  period_end TEXT NOT NULL,\n  total_activations INTEGER DEFAULT 0,\n  total_invocations INTEGER DEFAULT 0,\n  total_successes INTEGER DEFAULT 0,\n  total_failures INTEGER DEFAULT 0,\n  avg_value_score REAL DEFAULT 0.0,\n  estimated_time_saved REAL DEFAULT 0.0, -- in minutes\n  estimated_value_usd REAL DEFAULT 0.0, -- rough ROI estimate\n  metadata TEXT, -- JSON for additional metrics\n  computed_at TEXT NOT NULL DEFAULT (datetime('now')),\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Indexes for ROI queries\nCREATE INDEX IF NOT EXISTS idx_roi_type ON roi_metrics(metric_type);\nCREATE INDEX IF NOT EXISTS idx_roi_entity ON roi_metrics(entity_id);\nCREATE INDEX IF NOT EXISTS idx_roi_period ON roi_metrics(period_start, period_end);\nCREATE INDEX IF NOT EXISTS idx_roi_computed ON roi_metrics(computed_at);\n\n-- Value attribution mappings\nCREATE TABLE IF NOT EXISTS value_attributions (\n  id TEXT PRIMARY KEY,\n  usage_event_id TEXT NOT NULL REFERENCES skill_usage_events(id) ON DELETE CASCADE,\n  skill_id TEXT NOT NULL,\n  attribution_type TEXT NOT NULL, -- 'inline', 'metadata', 'session'\n  value_dimension TEXT NOT NULL, -- 'time_saved', 'quality_improved', 'error_prevented'\n  value_amount REAL NOT NULL,\n  confidence REAL NOT NULL CHECK(confidence >= 0 AND confidence <= 1),\n  metadata TEXT, -- JSON additional context\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Indexes for attribution queries\nCREATE INDEX IF NOT EXISTS idx_attributions_event ON value_attributions(usage_event_id);\nCREATE INDEX IF NOT EXISTS idx_attributions_skill ON value_attributions(skill_id);\nCREATE INDEX IF NOT EXISTS idx_attributions_type ON value_attributions(attribution_type);\n";
+/**
+ * Apply analytics schema to a database
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+export declare function initializeAnalyticsSchema(db: DatabaseType): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/src/analytics/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/analytics/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,o0JA2G5B,CAAA;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE9D,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAEhE"}