@arcbridge/core 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import Database from 'better-sqlite3';
+import { DatabaseSync } from 'node:sqlite';
 
 declare const ServiceSchema: z.ZodObject<{
     name: z.ZodString;
@@ -78,6 +78,13 @@ declare const ArcBridgeConfigSchema: z.ZodObject<{
     }, {
         ignore_paths?: string[] | undefined;
     }>>;
+    metrics: z.ZodDefault<z.ZodObject<{
+        auto_record: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        auto_record: boolean;
+    }, {
+        auto_record?: boolean | undefined;
+    }>>;
     sync: z.ZodDefault<z.ZodObject<{
         auto_detect_drift: z.ZodDefault<z.ZodBoolean>;
         drift_severity_threshold: z.ZodDefault<z.ZodEnum<["info", "warning", "error"]>>;
@@ -117,6 +124,9 @@ declare const ArcBridgeConfigSchema: z.ZodObject<{
     drift: {
         ignore_paths: string[];
     };
+    metrics: {
+        auto_record: boolean;
+    };
     sync: {
         auto_detect_drift: boolean;
         drift_severity_threshold: "info" | "warning" | "error";
@@ -148,6 +158,9 @@ declare const ArcBridgeConfigSchema: z.ZodObject<{
     drift?: {
         ignore_paths?: string[] | undefined;
     } | undefined;
+    metrics?: {
+        auto_record?: boolean | undefined;
+    } | undefined;
     sync?: {
         auto_detect_drift?: boolean | undefined;
         drift_severity_threshold?: "info" | "warning" | "error" | undefined;
@@ -707,13 +720,24 @@ declare const AgentRoleSchema: z.ZodObject<{
 }>;
 type AgentRole = z.infer<typeof AgentRoleSchema>;
 
-declare function openDatabase(dbPath: string): Database.Database;
-declare function openMemoryDatabase(): Database.Database;
+/** Re-export DatabaseSync as Database for use across the codebase. */
+type Database = DatabaseSync;
+declare function suppressSqliteWarning(): void;
+declare function openDatabase(dbPath: string): Database;
+declare function openMemoryDatabase(): Database;
+/**
+ * Wrap a synchronous function in a SQLite transaction (BEGIN/COMMIT/ROLLBACK).
+ * Supports nesting via SAVEPOINTs — inner calls create savepoints
+ * instead of starting a new transaction.
+ *
+ * fn must be synchronous — passing an async function will throw.
+ */
+declare function transaction<T>(db: Database, fn: () => T): T;
 
-declare const CURRENT_SCHEMA_VERSION = 1;
-declare function initializeSchema(db: Database.Database): void;
+declare const CURRENT_SCHEMA_VERSION = 2;
+declare function initializeSchema(db: Database): void;
 
-declare function migrate(db: Database.Database): void;
+declare function migrate(db: Database): void;
 
 interface InitProjectInput {
     name: string;
@@ -738,14 +762,14 @@ declare function generatePlan(targetDir: string, input: InitProjectInput): void;
 declare function generateAgentRoles(targetDir: string, template?: string): AgentRole[];
 
 interface GenerateDatabaseResult {
-    db: Database.Database;
+    db: Database;
     warnings: string[];
 }
 /**
  * Re-read arc42 files from disk and update the database.
  * Uses INSERT OR REPLACE to pick up changes made since initial generation.
  */
-declare function refreshFromDocs(db: Database.Database, targetDir: string): string[];
+declare function refreshFromDocs(db: Database, targetDir: string): string[];
 declare function generateDatabase(targetDir: string, input: InitProjectInput): GenerateDatabaseResult;
 
 interface IndexerOptions {
@@ -805,7 +829,7 @@ declare function discoverDotnetServices(projectRoot: string): DotnetProjectInfo[
  * Scan the project root for package dependency manifests (package.json, .csproj)
  * and write discovered dependencies to the package_dependencies table.
  */
-declare function indexPackageDependencies(db: Database.Database, projectRoot: string, service?: string): number;
+declare function indexPackageDependencies(db: Database, projectRoot: string, service?: string): number;
 
 type ProjectLanguage = "typescript" | "csharp" | "auto";
 /**
@@ -818,7 +842,7 @@ declare function detectProjectLanguage(projectRoot: string): "typescript" | "csh
  * Index a project, auto-detecting the language unless explicitly specified.
  * Dispatches to the TypeScript or .NET indexer accordingly.
  */
-declare function indexProject(db: Database.Database, options: IndexerOptions): Promise<IndexResult>;
+declare function indexProject(db: Database, options: IndexerOptions): Promise<IndexResult>;
 
 type DriftKind = "undocumented_module" | "missing_module" | "dependency_violation" | "unlinked_test" | "stale_adr" | "new_dependency";
 type DriftSeverity = "info" | "warning" | "error";
@@ -840,12 +864,12 @@ interface DriftOptions {
  * Compares building block code_paths against actual indexed files,
  * checks cross-block dependencies, and validates ADR references.
  */
-declare function detectDrift(db: Database.Database, options?: DriftOptions): DriftEntry[];
+declare function detectDrift(db: Database, options?: DriftOptions): DriftEntry[];
 /**
  * Write drift entries to the drift_log table.
  * Clears existing unresolved entries and inserts fresh ones.
  */
-declare function writeDriftLog(db: Database.Database, entries: DriftEntry[]): void;
+declare function writeDriftLog(db: Database, entries: DriftEntry[]): void;
 
 interface TaskInferenceResult {
     taskId: string;
@@ -857,11 +881,11 @@ interface TaskInferenceResult {
  * Infer task status from code state.
  * Checks if building block code exists, acceptance criteria symbols are present, etc.
  */
-declare function inferTaskStatuses(db: Database.Database, phaseId: string): TaskInferenceResult[];
+declare function inferTaskStatuses(db: Database, phaseId: string): TaskInferenceResult[];
 /**
  * Apply inferred statuses to the database and optionally write back to YAML.
  */
-declare function applyInferences(db: Database.Database, inferences: TaskInferenceResult[], projectRoot: string): void;
+declare function applyInferences(db: Database, inferences: TaskInferenceResult[], projectRoot: string): void;
 
 /**
  * Update a task's status in the YAML task file.
@@ -894,6 +918,102 @@ declare function syncScenarioToYaml(projectRoot: string, scenarioId: string, sta
  */
 declare function generateSyncFiles(targetDir: string, config: ArcBridgeConfig): string[];
 
+interface InsertActivityParams {
+    toolName: string;
+    action?: string;
+    model?: string;
+    agentRole?: string;
+    taskId?: string;
+    phaseId?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+    durationMs?: number;
+    driftCount?: number;
+    driftErrors?: number;
+    testPassCount?: number;
+    testFailCount?: number;
+    lintClean?: boolean;
+    typecheckClean?: boolean;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+interface QueryMetricsParams {
+    taskId?: string;
+    phaseId?: string;
+    model?: string;
+    agentRole?: string;
+    toolName?: string;
+    since?: string;
+    until?: string;
+    groupBy: "model" | "task" | "phase" | "tool" | "day" | "none";
+    limit: number;
+}
+interface ActivityRow {
+    id: number;
+    tool_name: string;
+    action: string | null;
+    model: string | null;
+    agent_role: string | null;
+    task_id: string | null;
+    phase_id: string | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    total_tokens: number | null;
+    cost_usd: number | null;
+    duration_ms: number | null;
+    drift_count: number | null;
+    drift_errors: number | null;
+    test_pass_count: number | null;
+    test_fail_count: number | null;
+    lint_clean: number | null;
+    typecheck_clean: number | null;
+    notes: string | null;
+    metadata: string;
+    recorded_at: string;
+}
+interface AggregatedRow {
+    groupKey: string;
+    activityCount: number;
+    sumTokens: number | null;
+    avgTokens: number | null;
+    sumCost: number | null;
+    avgDuration: number | null;
+    firstActivity: string;
+    lastActivity: string;
+}
+interface LatestQualitySnapshot {
+    driftCount: number | null;
+    driftErrors: number | null;
+    testPassCount: number | null;
+    testFailCount: number | null;
+    lintClean: boolean | null;
+    typecheckClean: boolean | null;
+    capturedAt: string | null;
+}
+interface SessionTotals {
+    totalCost: number;
+    totalTokens: number;
+    activityCount: number;
+}
+interface MetricsResult {
+    rows: ActivityRow[] | AggregatedRow[];
+    grouped: boolean;
+    qualitySnapshot: LatestQualitySnapshot;
+    totals: SessionTotals;
+    timeSpan: {
+        first: string;
+        last: string;
+    } | null;
+}
+type ExportFormat = "json" | "csv" | "markdown";
+
+declare function insertActivity(db: Database, params: InsertActivityParams): number;
+declare function getSessionTotals(db: Database, since?: string, model?: string): SessionTotals;
+declare function queryMetrics(db: Database, params: QueryMetricsParams): MetricsResult;
+declare function exportMetrics(db: Database, projectRoot: string, format: ExportFormat, params: Omit<QueryMetricsParams, "groupBy" | "limit">, maxRows?: number): string;
+
 interface ChangedFile {
     status: "added" | "modified" | "deleted" | "renamed";
     path: string;
@@ -911,7 +1031,7 @@ interface GitRef {
  * - "last-phase" → commit stored in arcbridge_meta under "phase_sync_commit", or HEAD~5 fallback
  * - anything else → treated as a literal git ref (branch, tag, SHA)
  */
-declare function resolveRef(projectRoot: string, since: string, db?: Database.Database): GitRef;
+declare function resolveRef(projectRoot: string, since: string, db?: Database): GitRef;
 /**
  * Get list of changed files between a ref and HEAD.
  */
@@ -927,7 +1047,7 @@ declare function getHeadSha(projectRoot: string): string | null;
 /**
  * Store the current sync point in arcbridge_meta.
  */
-declare function setSyncCommit(db: Database.Database, key: "last_sync_commit" | "phase_sync_commit", sha: string): void;
+declare function setSyncCommit(db: Database, key: "last_sync_commit" | "phase_sync_commit", sha: string): void;
 
 type TestOutcome = "passed" | "failed" | "missing" | "error";
 interface ScenarioTestResult {
@@ -953,7 +1073,7 @@ interface VerifyResult {
  *
  * Optionally filter by specific scenario IDs.
  */
-declare function verifyScenarios(db: Database.Database, projectRoot: string, options: {
+declare function verifyScenarios(db: Database, projectRoot: string, options: {
     testCommand: string;
     timeoutMs: number;
     scenarioIds?: string[];
@@ -988,4 +1108,4 @@ declare function loadConfig(projectRoot: string): {
     error: string | null;
 };
 
-export { type AdrFrontmatter, AdrFrontmatterSchema, type AgentRole, AgentRoleSchema, type ArcBridgeConfig, ArcBridgeConfigSchema, type BuildingBlock, BuildingBlockSchema, type BuildingBlocksFrontmatter, BuildingBlocksFrontmatterSchema, CURRENT_SCHEMA_VERSION, type ChangedFile, type DotnetProjectInfo, type DriftEntry, type DriftKind, type DriftOptions, type DriftSeverity, type ExtractedSymbol, type GenerateDatabaseResult, type GitRef, type IndexResult, type IndexerOptions, type InitProjectInput, type LoadRolesResult, type Phase, PhaseSchema, type PhasesFile, PhasesFileSchema, type ProjectLanguage, QualityCategorySchema, QualityPrioritySchema, type QualityScenario, QualityScenarioSchema, QualityScenarioStatusSchema, type QualityScenariosFile, QualityScenariosFileSchema, type ScenarioTestResult, type Service, type SymbolKind, type Task, type TaskFile, TaskFileSchema, type TaskInferenceResult, TaskSchema, type TestOutcome, type VerifyResult, addTaskToYaml, applyInferences, detectDrift, detectProjectLanguage, discoverDotnetServices, generateAgentRoles, generateArc42, generateConfig, generateDatabase, generatePlan, generateSyncFiles, getChangedFiles, getHeadSha, getUncommittedChanges, indexPackageDependencies, indexProject, inferTaskStatuses, initializeSchema, loadConfig, loadRole, loadRoles, migrate, openDatabase, openMemoryDatabase, refreshFromDocs, resolveRef, setSyncCommit, syncPhaseToYaml, syncScenarioToYaml, syncTaskToYaml, verifyScenarios, writeDriftLog };
+export { type ActivityRow, type AdrFrontmatter, AdrFrontmatterSchema, type AgentRole, AgentRoleSchema, type AggregatedRow, type ArcBridgeConfig, ArcBridgeConfigSchema, type BuildingBlock, BuildingBlockSchema, type BuildingBlocksFrontmatter, BuildingBlocksFrontmatterSchema, CURRENT_SCHEMA_VERSION, type ChangedFile, type Database, type DotnetProjectInfo, type DriftEntry, type DriftKind, type DriftOptions, type DriftSeverity, type ExportFormat, type ExtractedSymbol, type GenerateDatabaseResult, type GitRef, type IndexResult, type IndexerOptions, type InitProjectInput, type InsertActivityParams, type LatestQualitySnapshot, type LoadRolesResult, type MetricsResult, type Phase, PhaseSchema, type PhasesFile, PhasesFileSchema, type ProjectLanguage, QualityCategorySchema, QualityPrioritySchema, type QualityScenario, QualityScenarioSchema, QualityScenarioStatusSchema, type QualityScenariosFile, QualityScenariosFileSchema, type QueryMetricsParams, type ScenarioTestResult, type Service, type SessionTotals, type SymbolKind, type Task, type TaskFile, TaskFileSchema, type TaskInferenceResult, TaskSchema, type TestOutcome, type VerifyResult, addTaskToYaml, applyInferences, detectDrift, detectProjectLanguage, discoverDotnetServices, exportMetrics, generateAgentRoles, generateArc42, generateConfig, generateDatabase, generatePlan, generateSyncFiles, getChangedFiles, getHeadSha, getSessionTotals, getUncommittedChanges, indexPackageDependencies, indexProject, inferTaskStatuses, initializeSchema, insertActivity, loadConfig, loadRole, loadRoles, migrate, openDatabase, openMemoryDatabase, queryMetrics, refreshFromDocs, resolveRef, setSyncCommit, suppressSqliteWarning, syncPhaseToYaml, syncScenarioToYaml, syncTaskToYaml, transaction, verifyScenarios, writeDriftLog };