swarm-mail 1.3.0 → 1.5.0

package/dist/analytics/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Analytics Module
+ *
+ * Type-safe query builder and result formatters for SQL analytics.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { QueryBuilder, formatTable } from "swarm-mail/analytics";
+ *
+ * const query = new QueryBuilder()
+ *   .select(["type", "COUNT(*) as count"])
+ *   .from("events")
+ *   .where("project_key = ?", ["my-project"])
+ *   .groupBy("type")
+ *   .orderBy("count", "DESC")
+ *   .limit(10)
+ *   .withName("event-counts")
+ *   .withDescription("Event type counts by project")
+ *   .build();
+ *
+ * // Execute query (you provide the database adapter)
+ * const result = await db.query(query.sql, Object.values(query.parameters || {}));
+ *
+ * // Format output
+ * console.log(formatTable(result));
+ * ```
+ *
+ * @module analytics
+ */
+export { formatCSV, formatJSON, formatJSONL, formatTable } from "./formatters.js";
+export { QueryBuilder } from "./query-builder.js";
+export * from "./queries/index.js";
+export type { AnalyticsQuery, OutputFormat, QueryResult } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/analytics/queries/agent-activity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Query 4: Agent Activity
+ *
+ * Tracks agent activity levels by event count and time span.
+ */
+import type { AnalyticsQuery } from "../types.js";
+export interface AgentActivityFilters {
+    project_key?: string;
+    since?: number;
+}
+/**
+ * Build a query for agent activity analysis.
+ *
+ * Returns agent_name, event count, first event timestamp, last event timestamp,
+ * and active time span, ordered by event count descending.
+ *
+ * @param filters - Optional filters for project_key and time range
+ * @returns AnalyticsQuery ready for execution
+ */
+export declare function agentActivity(filters?: AgentActivityFilters): AnalyticsQuery;
+//# sourceMappingURL=agent-activity.d.ts.map

package/dist/analytics/queries/agent-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-activity.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/agent-activity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,oBAAoB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,cAAc,CA0B5E"}

package/dist/analytics/queries/checkpoint-frequency.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Checkpoint Frequency Query
+ *
+ * Analyzes how often agents create checkpoints.
+ * Useful for understanding checkpoint adoption and patterns.
+ */
+import type { AnalyticsQuery } from "../types.js";
+/**
+ * Pre-built query to measure checkpoint frequency per agent.
+ *
+ * Counts checkpoint_created events grouped by agent.
+ * Shows which agents are actively using checkpoints.
+ *
+ * @example
+ * ```typescript
+ * const adapter = await getSwarmMailLibSQL(projectPath);
+ * const db = await adapter.getDatabase();
+ * const result = await db.query(checkpointFrequency.sql);
+ * ```
+ */
+export declare const checkpointFrequency: AnalyticsQuery & {
+    buildQuery?: (filters: {
+        project_key?: string;
+    }) => AnalyticsQuery;
+};
+//# sourceMappingURL=checkpoint-frequency.d.ts.map

package/dist/analytics/queries/checkpoint-frequency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-frequency.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/checkpoint-frequency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAAc,GAAG;IAClD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CAyCnE,CAAC"}

package/dist/analytics/queries/failed-decompositions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Query 1: Failed Decompositions
+ *
+ * Analyzes decomposition failures by strategy, showing which strategies
+ * have the highest failure rates and average duration.
+ */
+import type { AnalyticsQuery } from "../types.js";
+export interface FailedDecompositionsFilters {
+    project_key?: string;
+    limit?: number;
+}
+/**
+ * Build a query for failed decompositions grouped by strategy.
+ *
+ * Returns strategy, failure count, and average duration for all failed
+ * subtask outcomes, ordered by failure count descending.
+ *
+ * @param filters - Optional filters for project_key and limit
+ * @returns AnalyticsQuery ready for execution
+ */
+export declare function failedDecompositions(filters?: FailedDecompositionsFilters): AnalyticsQuery;
+//# sourceMappingURL=failed-decompositions.d.ts.map

package/dist/analytics/queries/failed-decompositions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failed-decompositions.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/failed-decompositions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,2BAA2B;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,CAAC,EAAE,2BAA2B,GACnC,cAAc,CA0BhB"}

package/dist/analytics/queries/human-feedback.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Human Feedback Query
+ *
+ * Analyzes approval vs rejection rates from human review.
+ * Tracks review_feedback events to measure quality control.
+ */
+import type { AnalyticsQuery } from "../types.js";
+/**
+ * Pre-built query to analyze human feedback patterns.
+ *
+ * Counts approvals vs rejections from review_feedback events.
+ * Shows breakdown by status (approved vs needs_changes).
+ *
+ * @example
+ * ```typescript
+ * const adapter = await getSwarmMailLibSQL(projectPath);
+ * const db = await adapter.getDatabase();
+ * const result = await db.query(humanFeedback.sql);
+ * ```
+ */
+export declare const humanFeedback: AnalyticsQuery & {
+    buildQuery?: (filters: {
+        project_key?: string;
+    }) => AnalyticsQuery;
+};
+//# sourceMappingURL=human-feedback.d.ts.map

package/dist/analytics/queries/human-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-feedback.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/human-feedback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,cAAc,GAAG;IAC5C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CAqCnE,CAAC"}

package/dist/analytics/queries/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pre-built Analytics Queries
+ *
+ * Barrel export for all query functions.
+ */
+export type { AgentActivityFilters } from "./agent-activity.js";
+export { agentActivity } from "./agent-activity.js";
+export { checkpointFrequency } from "./checkpoint-frequency.js";
+export type { FailedDecompositionsFilters } from "./failed-decompositions.js";
+export { failedDecompositions } from "./failed-decompositions.js";
+export { humanFeedback } from "./human-feedback.js";
+export type { LockContentionFilters } from "./lock-contention.js";
+export { lockContention } from "./lock-contention.js";
+export type { MessageLatencyFilters } from "./message-latency.js";
+export { messageLatency } from "./message-latency.js";
+export { recoverySuccess } from "./recovery-success.js";
+export { scopeViolations } from "./scope-violations.js";
+export type { StrategySuccessRatesFilters } from "./strategy-success-rates.js";
+export { strategySuccessRates } from "./strategy-success-rates.js";
+export { taskDuration } from "./task-duration.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/queries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/analytics/queries/lock-contention.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Query 3: Lock Contention
+ *
+ * Identifies files with highest reservation counts and average hold times.
+ */
+import type { AnalyticsQuery } from "../types.js";
+export interface LockContentionFilters {
+    limit?: number;
+}
+/**
+ * Build a query for lock contention analysis.
+ *
+ * Returns path_pattern, reservation count, and average hold time for
+ * file reservations, ordered by reservation count descending.
+ *
+ * @param filters - Optional limit
+ * @returns AnalyticsQuery ready for execution
+ */
+export declare function lockContention(filters?: LockContentionFilters): AnalyticsQuery;
+//# sourceMappingURL=lock-contention.d.ts.map

package/dist/analytics/queries/lock-contention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-contention.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/lock-contention.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc,CAqB9E"}

package/dist/analytics/queries/message-latency.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Query 5: Message Latency
+ *
+ * Calculates p50, p95, p99 response times for messages.
+ *
+ * Note: SQLite doesn't have native percentile functions, so we use
+ * a simplified approach that orders by latency and extracts values
+ * at approximate percentile positions.
+ */
+import type { AnalyticsQuery } from "../types.js";
+export interface MessageLatencyFilters {
+    project_key?: string;
+}
+/**
+ * Build a query for message latency percentiles.
+ *
+ * Returns approximate p50, p95, p99 latency values for messages.
+ * Uses a CTE to compute latencies, then calculates percentiles.
+ *
+ * @param filters - Optional filters for project_key
+ * @returns AnalyticsQuery ready for execution
+ */
+export declare function messageLatency(filters?: MessageLatencyFilters): AnalyticsQuery;
+//# sourceMappingURL=message-latency.d.ts.map

package/dist/analytics/queries/message-latency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-latency.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/message-latency.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,cAAc,CA8ChB"}

package/dist/analytics/queries/recovery-success.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Recovery Success Query
+ *
+ * Calculates success rate for deferred task resolution.
+ * Tracks how often deferred tasks resolve successfully vs fail.
+ */
+import type { AnalyticsQuery } from "../types.js";
+/**
+ * Pre-built query to measure recovery success rate.
+ *
+ * Calculates percentage of deferred tasks that resolved successfully
+ * vs those that were rejected or failed.
+ *
+ * @example
+ * ```typescript
+ * const adapter = await getSwarmMailLibSQL(projectPath);
+ * const db = await adapter.getDatabase();
+ * const result = await db.query(recoverySuccess.sql);
+ * ```
+ */
+export declare const recoverySuccess: AnalyticsQuery & {
+    buildQuery?: (filters: {
+        project_key?: string;
+    }) => AnalyticsQuery;
+};
+//# sourceMappingURL=recovery-success.d.ts.map

package/dist/analytics/queries/recovery-success.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-success.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/recovery-success.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,GAAG;IAC9C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CAmCnE,CAAC"}

package/dist/analytics/queries/scope-violations.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Scope Violations Query
+ *
+ * Identifies files touched outside the agent's assigned scope.
+ * Useful for detecting agents that modify files they weren't
+ * supposed to touch.
+ */
+import type { AnalyticsQuery } from "../types.js";
+/**
+ * Pre-built query to find scope violations.
+ *
+ * Extracts files_touched from task_completed events and compares
+ * against assigned scope (from task data).
+ *
+ * @example
+ * ```typescript
+ * const adapter = await getSwarmMailLibSQL(projectPath);
+ * const db = await adapter.getDatabase();
+ * const result = await db.query(scopeViolations.sql);
+ * ```
+ */
+export declare const scopeViolations: AnalyticsQuery & {
+    buildQuery?: (filters: {
+        project_key?: string;
+    }) => AnalyticsQuery;
+};
+//# sourceMappingURL=scope-violations.d.ts.map

package/dist/analytics/queries/scope-violations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-violations.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/scope-violations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,GAAG;IAC9C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CAyCnE,CAAC"}

package/dist/analytics/queries/strategy-success-rates.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Query 2: Strategy Success Rates
+ *
+ * Calculates success rate percentage for each decomposition strategy.
+ */
+import type { AnalyticsQuery } from "../types.js";
+export interface StrategySuccessRatesFilters {
+    project_key?: string;
+}
+/**
+ * Build a query for strategy success rates.
+ *
+ * Returns strategy, total attempts, successful count, failed count, and
+ * success rate percentage, ordered by success rate descending.
+ *
+ * @param filters - Optional filters for project_key
+ * @returns AnalyticsQuery ready for execution
+ */
+export declare function strategySuccessRates(filters?: StrategySuccessRatesFilters): AnalyticsQuery;
+//# sourceMappingURL=strategy-success-rates.d.ts.map

package/dist/analytics/queries/strategy-success-rates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-success-rates.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/strategy-success-rates.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,2BAA2B;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,CAAC,EAAE,2BAA2B,GACnC,cAAc,CAuBhB"}

package/dist/analytics/queries/task-duration.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Task Duration Query
+ *
+ * Calculates p50, p95, and p99 percentiles for task completion times.
+ * Uses window functions to compute percentiles from task start/end events.
+ */
+import type { AnalyticsQuery } from "../types.js";
+/**
+ * Pre-built query to calculate task duration percentiles.
+ *
+ * Computes p50 (median), p95, and p99 durations by:
+ * 1. Finding task_started and task_completed event pairs
+ * 2. Calculating duration = completed_timestamp - started_timestamp
+ * 3. Using ORDER BY + LIMIT to approximate percentiles
+ *
+ * Note: libSQL doesn't have percentile_cont, so we use row counting
+ * to approximate percentiles.
+ *
+ * @example
+ * ```typescript
+ * const adapter = await getSwarmMailLibSQL(projectPath);
+ * const db = await adapter.getDatabase();
+ * const result = await db.query(taskDuration.sql);
+ * ```
+ */
+export declare const taskDuration: AnalyticsQuery & {
+    buildQuery?: (filters: {
+        project_key?: string;
+    }) => AnalyticsQuery;
+};
+//# sourceMappingURL=task-duration.d.ts.map

package/dist/analytics/queries/task-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-duration.d.ts","sourceRoot":"","sources":["../../../src/analytics/queries/task-duration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,GAAG;IAC3C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CAqEnE,CAAC"}

package/dist/analytics/query-builder.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Analytics Query Builder
+ *
+ * Fluent API for constructing SQL queries with type safety.
+ * Produces parameterized queries to prevent SQL injection.
+ */
+import type { AnalyticsQuery } from "./types.js";
+/**
+ * Fluent query builder for constructing SQL queries.
+ *
+ * Supports SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT.
+ * Accumulates parameters from WHERE and HAVING clauses.
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder()
+ *   .select(["type", "COUNT(*) as count"])
+ *   .from("events")
+ *   .where("project_key = ?", ["my-project"])
+ *   .groupBy("type")
+ *   .orderBy("count", "DESC")
+ *   .limit(10)
+ *   .withName("event-counts")
+ *   .withDescription("Event type counts by project")
+ *   .build();
+ * ```
+ */
+export declare class QueryBuilder {
+    private selectClause;
+    private fromClause;
+    private whereClauses;
+    private groupByClause;
+    private havingClauses;
+    private orderByClause;
+    private limitClause;
+    private queryName;
+    private queryDescription;
+    private params;
+    /**
+     * Add SELECT clause with column expressions.
+     *
+     * @param columns - Array of column names or expressions (e.g., ["id", "COUNT(*) as count"])
+     */
+    select(columns: string[]): this;
+    /**
+     * Set FROM clause with table name.
+     *
+     * @param table - Table name to query from
+     */
+    from(table: string): this;
+    /**
+     * Add WHERE condition with optional parameters.
+     *
+     * Multiple calls are combined with AND.
+     *
+     * @param condition - SQL condition (use ? for parameter placeholders)
+     * @param params - Parameter values to bind
+     */
+    where(condition: string, params?: unknown[]): this;
+    /**
+     * Set GROUP BY clause.
+     *
+     * @param column - Column to group by
+     */
+    groupBy(column: string): this;
+    /**
+     * Add HAVING condition with optional parameters.
+     *
+     * Multiple calls are combined with AND.
+     *
+     * @param condition - SQL condition (use ? for parameter placeholders)
+     * @param params - Parameter values to bind
+     */
+    having(condition: string, params?: unknown[]): this;
+    /**
+     * Set ORDER BY clause.
+     *
+     * @param column - Column to sort by
+     * @param direction - Sort direction (ASC or DESC)
+     */
+    orderBy(column: string, direction?: "ASC" | "DESC"): this;
+    /**
+     * Set LIMIT clause.
+     *
+     * @param count - Maximum number of rows to return
+     */
+    limit(count: number): this;
+    /**
+     * Set query name (for AnalyticsQuery.name).
+     *
+     * @param name - Unique identifier for this query
+     */
+    withName(name: string): this;
+    /**
+     * Set query description (for AnalyticsQuery.description).
+     *
+     * @param description - Human-readable description of what query does
+     */
+    withDescription(description: string): this;
+    /**
+     * Build the final AnalyticsQuery object.
+     *
+     * Constructs SQL string from accumulated clauses and returns
+     * AnalyticsQuery with name, description, sql, and parameters.
+     *
+     * @returns Complete AnalyticsQuery ready for execution
+     */
+    build(): AnalyticsQuery;
+}
+//# sourceMappingURL=query-builder.d.ts.map

package/dist/analytics/query-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/analytics/query-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,MAAM,CAAiB;IAE/B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAK/B;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzB;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,IAAI;IAMtD;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,IAAI;IAMvD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,KAAK,GAAG,MAAc,GAAG,IAAI;IAKhE;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK1B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK1C;;;;;;;OAOG;IACH,KAAK,IAAI,cAAc;CA2DvB"}

package/dist/analytics/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Analytics Query Builder Types
+ *
+ * Type-safe interfaces for SQL query construction and result formatting.
+ */
+/**
+ * Represents a named analytics query with optional parameters.
+ */
+export interface AnalyticsQuery {
+    /** Unique identifier for the query */
+    name: string;
+    /** Human-readable description of what the query does */
+    description: string;
+    /** SQL query string (may include ? placeholders for parameters) */
+    sql: string;
+    /** Optional parameters to bind to the SQL query */
+    parameters?: Record<string, unknown>;
+}
+/**
+ * Result of executing an analytics query.
+ */
+export interface QueryResult {
+    /** Column names in result set */
+    columns: string[];
+    /** Result rows as objects (column name -> value) */
+    rows: Record<string, unknown>[];
+    /** Total number of rows returned */
+    rowCount: number;
+    /** Query execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * Supported output formats for query results.
+ */
+export type OutputFormat = "table" | "json" | "csv" | "jsonl";
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,eAAe,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC"}

package/dist/analytics.d.ts

@@ -0,0 +1,46 @@
+import type { DatabaseAdapter } from "./types/database.js";
+/**
+ * Analytics query definition for pre-built queries.
+ * Based on Google's Four Golden Signals: Latency, Traffic, Errors, Saturation.
+ */
+export interface AnalyticsQuery {
+    /** Short name for CLI reference (e.g., "latency", "traffic") */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Parameterized SQL query (use ? placeholders for since/until) */
+    sql: string;
+    /** Format query results as string (table/json/csv handled by caller) */
+    format: (rows: unknown[]) => string;
+}
+/**
+ * Pre-built analytics queries for swarm-db CLI.
+ * Based on Four Golden Signals monitoring framework.
+ */
+export declare const ANALYTICS_QUERIES: AnalyticsQuery[];
+/**
+ * Run a pre-built analytics query against the database.
+ *
+ * @param db Database adapter
+ * @param queryName Name of the query to run (e.g., "latency", "traffic")
+ * @param options Query options
+ * @param options.since Filter events after this timestamp
+ * @param options.until Filter events before this timestamp
+ * @param options.format Output format: "table" (default), "json", or "csv"
+ * @returns Formatted query results as string
+ *
+ * @throws Error if query name is not found
+ *
+ * @example
+ * ```typescript
+ * const db = await createInMemoryDatabaseAdapter();
+ * const result = await runAnalyticsQuery(db, "latency", { format: "json" });
+ * console.log(result);
+ * ```
+ */
+export declare function runAnalyticsQuery(db: DatabaseAdapter, queryName: string, options?: {
+    since?: Date;
+    until?: Date;
+    format?: "table" | "json" | "csv";
+}): Promise<string>;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAAc,EAuH7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACtC,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IACT,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;CAClC,GACC,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

package/dist/cli/db.d.ts

@@ -0,0 +1,73 @@
+/**
+ * CLI DB Commands Implementation
+ *
+ * Implements swarm-db CLI commands:
+ * - query: execute raw SQL
+ * - analytics: run pre-built queries
+ * - list: show available analytics
+ */
+import type { OutputFormat } from "../analytics/types.js";
+/**
+ * Analytics command definition
+ */
+export interface AnalyticsCommand {
+    name: string;
+    description: string;
+}
+/**
+ * Options for executeQueryCommand
+ */
+export interface QueryOptions {
+    sql: string;
+    db: string;
+    format: OutputFormat;
+    limit?: number;
+}
+/**
+ * Options for executeAnalyticsCommand
+ */
+export interface AnalyticsOptions {
+    command: string;
+    db: string;
+    format: OutputFormat;
+    since?: string;
+    until?: string;
+    project?: string;
+    epic?: string;
+}
+/**
+ * Validate SQL query is read-only (SELECT only).
+ *
+ * @param sql - SQL query to validate
+ * @throws Error if query is not a SELECT
+ */
+export declare function validateSQL(sql: string): void;
+/**
+ * Parse time range string (7d, 24h, 30m) into a Date.
+ *
+ * @param range - Time range string (e.g., "7d", "24h", "30m")
+ * @returns Date object representing the point in time
+ * @throws Error if format is invalid
+ */
+export declare function parseTimeRange(range: string): Date;
+/**
+ * List all available analytics commands with descriptions.
+ *
+ * @returns Array of analytics command definitions
+ */
+export declare function listAnalyticsCommands(): AnalyticsCommand[];
+/**
+ * Execute a raw SQL query command.
+ *
+ * @param options - Query options including SQL, database path, format, and limit
+ * @returns Formatted query result as string
+ */
+export declare function executeQueryCommand(options: QueryOptions): Promise<string>;
+/**
+ * Execute an analytics command.
+ *
+ * @param options - Analytics options including command name, filters, and format
+ * @returns Formatted query result as string
+ */
+export declare function executeAnalyticsCommand(options: AnalyticsOptions): Promise<string>;
+//# sourceMappingURL=db.d.ts.map

package/dist/cli/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/cli/db.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,uBAAuB,CAAC;AAIvE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAa7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAgClD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,EAAE,CAmD1D;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,YAAY,GACnB,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,MAAM,CAAC,CAsCjB"}