@stackmemoryai/stackmemory 0.2.8 → 0.3.0

package/dist/core/retrieval/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/retrieval/types.ts"],
+  "sourcesContent": ["/**\n * Types for LLM-Driven Context Retrieval System\n * Implements intelligent context selection based on compressed summaries\n */\n\nimport { Frame, Anchor, Event } from '../context/frame-manager.js';\nimport { StackMemoryQuery } from '../query/query-parser.js';\n\n/**\n * Compressed summary of recent session activity\n */\nexport interface RecentSessionSummary {\n  /** Recent frames with their key attributes */\n  frames: FrameSummary[];\n  /** Dominant operations performed */\n  dominantOperations: OperationSummary[];\n  /** Files that were touched */\n  filesTouched: FileSummary[];\n  /** Errors encountered */\n  errorsEncountered: ErrorSummary[];\n  /** Time range covered */\n  timeRange: {\n    start: number;\n    end: number;\n    durationMs: number;\n  };\n}\n\nexport interface FrameSummary {\n  frameId: string;\n  name: string;\n  type: string;\n  depth: number;\n  eventCount: number;\n  anchorCount: number;\n  score: number;\n  createdAt: number;\n  closedAt?: number;\n  digestPreview?: string;\n}\n\nexport interface OperationSummary {\n  operation: string;\n  count: number;\n  lastOccurrence: number;\n  successRate: number;\n}\n\nexport interface FileSummary {\n  path: string;\n  operationCount: number;\n  lastModified: number;\n  operations: string[];\n}\n\nexport interface ErrorSummary {\n  errorType: string;\n  message: string;\n  count: number;\n  lastOccurrence: number;\n  resolved: boolean;\n}\n\n/**\n * Historical patterns extracted from memory\n */\nexport interface HistoricalPatterns {\n  /** Frame counts by topic */\n  topicFrameCounts: Record<string, number>;\n  /** Key decisions made */\n  keyDecisions: DecisionSummary[];\n  /** Recurring issues */\n  recurringIssues: IssueSummary[];\n  /** Common tool sequences */\n  commonToolSequences: ToolSequence[];\n  /** Time-based activity patterns */\n  activityPatterns: ActivityPattern[];\n}\n\nexport interface DecisionSummary {\n  id: string;\n  text: string;\n  frameId: string;\n  timestamp: number;\n  impact: 'low' | 'medium' | 'high';\n  relatedFiles?: string[];\n}\n\nexport interface IssueSummary {\n  issueType: string;\n  occurrenceCount: number;\n  lastSeen: number;\n  resolutionRate: number;\n  commonFixes?: string[];\n}\n\nexport interface ToolSequence {\n  pattern: string;\n  frequency: number;\n  avgDuration: number;\n  successRate: number;\n}\n\nexport interface ActivityPattern {\n  periodType: 'hourly' | 'daily' | 'weekly';\n  peakPeriods: string[];\n  avgEventsPerPeriod: number;\n}\n\n/**\n * Queryable indices for fast retrieval\n */\nexport interface QueryableIndices {\n  /** Index by error type */\n  byErrorType: Record<string, string[]>; // errorType -> frameIds\n  /** Index by timeframe */\n  byTimeframe: Record<string, string[]>; // timeKey -> frameIds\n  /** Index by contributor */\n  byContributor: Record<string, string[]>; // userId -> frameIds\n  /** Index by topic */\n  byTopic: Record<string, string[]>; // topic -> frameIds\n  /** Index by file */\n  byFile: Record<string, string[]>; // filePath -> frameIds\n}\n\n/**\n * Complete compressed summary for LLM analysis\n */\nexport interface CompressedSummary {\n  /** Project identifier */\n  projectId: string;\n  /** Generation timestamp */\n  generatedAt: number;\n  /** Recent session summary */\n  recentSession: RecentSessionSummary;\n  /** Historical patterns */\n  historicalPatterns: HistoricalPatterns;\n  /** Queryable indices */\n  queryableIndices: QueryableIndices;\n  /** Summary statistics */\n  stats: SummaryStats;\n}\n\nexport interface SummaryStats {\n  totalFrames: number;\n  totalEvents: number;\n  totalAnchors: number;\n  totalDecisions: number;\n  oldestFrame: number;\n  newestFrame: number;\n  avgFrameDepth: number;\n  avgEventsPerFrame: number;\n}\n\n/**\n * LLM analysis request\n */\nexport interface LLMAnalysisRequest {\n  /** Current user query */\n  currentQuery: string;\n  /** Parsed structured query */\n  parsedQuery?: StackMemoryQuery;\n  /** Compressed summary */\n  compressedSummary: CompressedSummary;\n  /** Token budget for context */\n  tokenBudget: number;\n  /** Optional hints for retrieval */\n  hints?: RetrievalHints;\n}\n\nexport interface RetrievalHints {\n  /** Prefer recent frames */\n  preferRecent?: boolean;\n  /** Focus on specific topics */\n  focusTopics?: string[];\n  /** Include error context */\n  includeErrors?: boolean;\n  /** Include decision history */\n  includeDecisions?: boolean;\n  /** Minimum relevance score */\n  minRelevance?: number;\n}\n\n/**\n * LLM analysis response\n */\nexport interface LLMAnalysisResponse {\n  /** Reasoning for the retrieval decision (auditable) */\n  reasoning: string;\n  /** Frames to retrieve with priority order */\n  framesToRetrieve: FrameRetrievalPlan[];\n  /** Confidence score (0.0 - 1.0) */\n  confidenceScore: number;\n  /** Additional context recommendations */\n  recommendations: ContextRecommendation[];\n  /** Analysis metadata */\n  metadata: AnalysisMetadata;\n}\n\nexport interface FrameRetrievalPlan {\n  frameId: string;\n  priority: number; // 1-10, higher = more important\n  reason: string;\n  includeEvents: boolean;\n  includeAnchors: boolean;\n  includeDigest: boolean;\n  estimatedTokens: number;\n}\n\nexport interface ContextRecommendation {\n  type: 'include' | 'exclude' | 'summarize';\n  target: string; // frameId, anchorId, or description\n  reason: string;\n  impact: 'low' | 'medium' | 'high';\n}\n\nexport interface AnalysisMetadata {\n  analysisTimeMs: number;\n  summaryTokens: number;\n  queryComplexity: 'simple' | 'moderate' | 'complex';\n  matchedPatterns: string[];\n  fallbackUsed: boolean;\n}\n\n/**\n * Retrieved context result\n */\nexport interface RetrievedContext {\n  /** Assembled context string */\n  context: string;\n  /** Frames included */\n  frames: Frame[];\n  /** Anchors included */\n  anchors: Anchor[];\n  /** Events included */\n  events: Event[];\n  /** LLM analysis that drove retrieval */\n  analysis: LLMAnalysisResponse;\n  /** Token usage */\n  tokenUsage: {\n    budget: number;\n    used: number;\n    remaining: number;\n  };\n  /** Retrieval metadata */\n  metadata: RetrievalMetadata;\n}\n\nexport interface RetrievalMetadata {\n  retrievalTimeMs: number;\n  cacheHit: boolean;\n  framesScanned: number;\n  framesIncluded: number;\n  compressionRatio: number;\n}\n\n/**\n * Configuration for the retrieval system\n */\nexport interface RetrievalConfig {\n  /** Maximum frames to include in summary */\n  maxSummaryFrames: number;\n  /** Default token budget */\n  defaultTokenBudget: number;\n  /** Cache TTL in seconds */\n  cacheTtlSeconds: number;\n  /** Minimum confidence to use LLM suggestions */\n  minConfidenceThreshold: number;\n  /** Enable fallback to heuristic retrieval */\n  enableFallback: boolean;\n  /** LLM provider configuration */\n  llmConfig: {\n    provider: 'anthropic' | 'openai' | 'local';\n    model: string;\n    maxTokens: number;\n    temperature: number;\n  };\n}\n\nexport const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {\n  maxSummaryFrames: 15,\n  defaultTokenBudget: 8000,\n  cacheTtlSeconds: 300,\n  minConfidenceThreshold: 0.6,\n  enableFallback: true,\n  llmConfig: {\n    provider: 'anthropic',\n    model: 'claude-3-haiku-20240307',\n    maxTokens: 1024,\n    temperature: 0.3,\n  },\n};\n"],
+  "mappings": "AAuRO,MAAM,2BAA4C;AAAA,EACvD,kBAAkB;AAAA,EAClB,oBAAoB;AAAA,EACpB,iBAAiB;AAAA,EACjB,wBAAwB;AAAA,EACxB,gBAAgB;AAAA,EAChB,WAAW;AAAA,IACT,UAAU;AAAA,IACV,OAAO;AAAA,IACP,WAAW;AAAA,IACX,aAAa;AAAA,EACf;AACF;",
+  "names": []
+}

package/dist/core/session/index.js

@@ -0,0 +1,11 @@
+import {
+  SessionManager,
+  sessionManager,
+  FrameQueryMode
+} from "./session-manager.js";
+export {
+  FrameQueryMode,
+  SessionManager,
+  sessionManager
+};
+//# sourceMappingURL=index.js.map

package/dist/core/session/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/session/index.ts"],
+  "sourcesContent": ["export { \n  SessionManager, \n  sessionManager,\n  type Session,\n  type SessionOptions,\n  FrameQueryMode \n} from './session-manager.js';"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EAGA;AAAA,OACK;",
+  "names": []
+}

package/dist/core/session/session-manager.js

@@ -0,0 +1,297 @@
+import { v4 as uuidv4 } from "uuid";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as crypto from "crypto";
+import { logger } from "../monitoring/logger.js";
+import { SystemError, ErrorCode } from "../errors/index.js";
+var FrameQueryMode = /* @__PURE__ */ ((FrameQueryMode2) => {
+  FrameQueryMode2["CURRENT_SESSION"] = "current";
+  FrameQueryMode2["PROJECT_ACTIVE"] = "project";
+  FrameQueryMode2["ALL_ACTIVE"] = "all";
+  FrameQueryMode2["HISTORICAL"] = "historical";
+  return FrameQueryMode2;
+})(FrameQueryMode || {});
+class SessionManager {
+  static instance;
+  sessionsDir;
+  currentSession = null;
+  STALE_THRESHOLD = 24 * 60 * 60 * 1e3;
+  // 24 hours
+  constructor() {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+    this.sessionsDir = path.join(homeDir, ".stackmemory", "sessions");
+  }
+  static getInstance() {
+    if (!SessionManager.instance) {
+      SessionManager.instance = new SessionManager();
+    }
+    return SessionManager.instance;
+  }
+  async initialize() {
+    try {
+      await fs.mkdir(this.sessionsDir, { recursive: true });
+      await fs.mkdir(path.join(this.sessionsDir, "projects"), { recursive: true });
+      await fs.mkdir(path.join(this.sessionsDir, "history"), { recursive: true });
+    } catch (error) {
+      throw new SystemError(
+        "Failed to initialize session directories",
+        ErrorCode.INITIALIZATION_ERROR,
+        { error, sessionsDir: this.sessionsDir }
+      );
+    }
+  }
+  async getOrCreateSession(options) {
+    if (options?.sessionId) {
+      const session = await this.loadSession(options.sessionId);
+      if (session) {
+        this.currentSession = session;
+        return session;
+      }
+    }
+    const envSessionId = process.env.STACKMEMORY_SESSION;
+    if (envSessionId) {
+      const session = await this.loadSession(envSessionId);
+      if (session) {
+        this.currentSession = session;
+        return session;
+      }
+    }
+    const projectHash = await this.getProjectHash(options?.projectPath);
+    const branch = options?.branch || await this.getGitBranch(options?.projectPath);
+    if (projectHash) {
+      const branchSession = await this.findProjectBranchSession(projectHash, branch);
+      if (branchSession && this.isSessionRecent(branchSession)) {
+        await this.touchSession(branchSession);
+        this.currentSession = branchSession;
+        return branchSession;
+      }
+      const lastActive = await this.findLastActiveSession(projectHash);
+      if (lastActive && this.isSessionRecent(lastActive)) {
+        await this.touchSession(lastActive);
+        this.currentSession = lastActive;
+        return lastActive;
+      }
+    }
+    const newSession = await this.createSession({
+      projectId: projectHash || "global",
+      branch,
+      metadata: options?.metadata
+    });
+    this.currentSession = newSession;
+    return newSession;
+  }
+  async createSession(params) {
+    const session = {
+      sessionId: uuidv4(),
+      runId: uuidv4(),
+      projectId: params.projectId,
+      branch: params.branch,
+      startedAt: Date.now(),
+      lastActiveAt: Date.now(),
+      metadata: {
+        ...params.metadata,
+        user: process.env.USER,
+        environment: process.env.NODE_ENV || "development",
+        cliVersion: process.env.npm_package_version
+      },
+      state: "active"
+    };
+    await this.saveSession(session);
+    await this.setProjectActiveSession(params.projectId, session.sessionId);
+    this.currentSession = session;
+    logger.info("Created new session", {
+      sessionId: session.sessionId,
+      projectId: session.projectId,
+      branch: session.branch
+    });
+    return session;
+  }
+  async loadSession(sessionId) {
+    try {
+      const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+      const data = await fs.readFile(sessionPath, "utf-8");
+      return JSON.parse(data);
+    } catch (error) {
+      try {
+        const historyPath = path.join(this.sessionsDir, "history", `${sessionId}.json`);
+        const data = await fs.readFile(historyPath, "utf-8");
+        return JSON.parse(data);
+      } catch {
+        return null;
+      }
+    }
+  }
+  async saveSession(session) {
+    const sessionPath = path.join(this.sessionsDir, `${session.sessionId}.json`);
+    await fs.writeFile(sessionPath, JSON.stringify(session, null, 2));
+  }
+  async suspendSession(sessionId) {
+    const id = sessionId || this.currentSession?.sessionId;
+    if (!id) return;
+    const session = await this.loadSession(id);
+    if (session) {
+      session.state = "suspended";
+      session.lastActiveAt = Date.now();
+      await this.saveSession(session);
+    }
+  }
+  async resumeSession(sessionId) {
+    const session = await this.loadSession(sessionId);
+    if (!session) {
+      throw new SystemError(
+        "Session not found",
+        ErrorCode.NOT_FOUND,
+        { sessionId }
+      );
+    }
+    session.state = "active";
+    session.lastActiveAt = Date.now();
+    await this.saveSession(session);
+    this.currentSession = session;
+    return session;
+  }
+  async closeSession(sessionId) {
+    const id = sessionId || this.currentSession?.sessionId;
+    if (!id) return;
+    const session = await this.loadSession(id);
+    if (session) {
+      session.state = "closed";
+      session.lastActiveAt = Date.now();
+      const sessionPath = path.join(this.sessionsDir, `${session.sessionId}.json`);
+      const historyPath = path.join(this.sessionsDir, "history", `${session.sessionId}.json`);
+      await fs.rename(sessionPath, historyPath);
+    }
+  }
+  async listSessions(filter) {
+    const sessions = [];
+    const files = await fs.readdir(this.sessionsDir);
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        const session = await this.loadSession(file.replace(".json", ""));
+        if (session) {
+          sessions.push(session);
+        }
+      }
+    }
+    return sessions.filter((s) => {
+      if (filter?.projectId && s.projectId !== filter.projectId) return false;
+      if (filter?.state && s.state !== filter.state) return false;
+      if (filter?.branch && s.branch !== filter.branch) return false;
+      return true;
+    });
+  }
+  async mergeSessions(sourceId, targetId) {
+    const source = await this.loadSession(sourceId);
+    const target = await this.loadSession(targetId);
+    if (!source || !target) {
+      throw new SystemError(
+        "Session not found for merge",
+        ErrorCode.NOT_FOUND,
+        { sourceId, targetId }
+      );
+    }
+    target.metadata = {
+      ...target.metadata,
+      ...source.metadata,
+      tags: [...target.metadata.tags || [], ...source.metadata.tags || []]
+    };
+    target.lastActiveAt = Date.now();
+    await this.closeSession(sourceId);
+    await this.saveSession(target);
+    logger.info("Merged sessions", {
+      source: sourceId,
+      target: targetId
+    });
+    return target;
+  }
+  async cleanupStaleSessions(maxAge = 30 * 24 * 60 * 60 * 1e3) {
+    const historyDir = path.join(this.sessionsDir, "history");
+    const files = await fs.readdir(historyDir);
+    const cutoff = Date.now() - maxAge;
+    let cleaned = 0;
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        const filePath = path.join(historyDir, file);
+        const stats = await fs.stat(filePath);
+        if (stats.mtimeMs < cutoff) {
+          await fs.unlink(filePath);
+          cleaned++;
+        }
+      }
+    }
+    logger.info(`Cleaned up ${cleaned} stale sessions`);
+    return cleaned;
+  }
+  getCurrentSession() {
+    return this.currentSession;
+  }
+  getSessionRunId() {
+    return this.currentSession?.runId || uuidv4();
+  }
+  async getProjectHash(projectPath) {
+    try {
+      const cwd = projectPath || process.cwd();
+      const path2 = await import("path");
+      const projectName = path2.basename(cwd);
+      if (projectName === "stackmemory") {
+        return "stackmemory-demo";
+      }
+      const hash = crypto.createHash("sha256");
+      hash.update(cwd);
+      return hash.digest("hex").substring(0, 12);
+    } catch {
+      return null;
+    }
+  }
+  async getGitBranch(projectPath) {
+    try {
+      const { execSync } = await import("child_process");
+      const cwd = projectPath || process.cwd();
+      const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        encoding: "utf-8"
+      }).trim();
+      return branch;
+    } catch {
+      return void 0;
+    }
+  }
+  async findProjectBranchSession(projectHash, branch) {
+    if (!branch) return null;
+    const sessions = await this.listSessions({
+      projectId: projectHash,
+      state: "active",
+      branch
+    });
+    return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0] || null;
+  }
+  async findLastActiveSession(projectHash) {
+    const sessions = await this.listSessions({
+      projectId: projectHash,
+      state: "active"
+    });
+    return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0] || null;
+  }
+  async setProjectActiveSession(projectId, sessionId) {
+    const projectFile = path.join(this.sessionsDir, "projects", `${projectId}.json`);
+    await fs.writeFile(projectFile, JSON.stringify({
+      projectId,
+      activeSessionId: sessionId,
+      updatedAt: Date.now()
+    }, null, 2));
+  }
+  isSessionRecent(session) {
+    return Date.now() - session.lastActiveAt < this.STALE_THRESHOLD;
+  }
+  async touchSession(session) {
+    session.lastActiveAt = Date.now();
+    await this.saveSession(session);
+  }
+}
+const sessionManager = SessionManager.getInstance();
+export {
+  FrameQueryMode,
+  SessionManager,
+  sessionManager
+};
+//# sourceMappingURL=session-manager.js.map

package/dist/core/session/session-manager.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/session/session-manager.ts"],
+  "sourcesContent": ["/**\n * Session Management for StackMemory\n * Provides session persistence and recovery across CLI invocations\n */\n\nimport { v4 as uuidv4 } from 'uuid';\nimport * as fs from 'fs/promises';\nimport * as path from 'path';\nimport * as crypto from 'crypto';\nimport { logger } from '../monitoring/logger.js';\nimport { SystemError, ErrorCode } from '../errors/index.js';\n\nexport interface Session {\n  sessionId: string;\n  runId: string;\n  projectId: string;\n  branch?: string;\n  startedAt: number;\n  lastActiveAt: number;\n  metadata: {\n    user?: string;\n    environment?: string;\n    tags?: string[];\n    cliVersion?: string;\n  };\n  state: 'active' | 'suspended' | 'closed';\n}\n\nexport interface SessionOptions {\n  sessionId?: string;\n  projectPath?: string;\n  branch?: string;\n  metadata?: Session['metadata'];\n}\n\nexport enum FrameQueryMode {\n  CURRENT_SESSION = 'current',\n  PROJECT_ACTIVE = 'project',\n  ALL_ACTIVE = 'all',\n  HISTORICAL = 'historical'\n}\n\nexport class SessionManager {\n  private static instance: SessionManager;\n  private sessionsDir: string;\n  private currentSession: Session | null = null;\n  private readonly STALE_THRESHOLD = 24 * 60 * 60 * 1000; // 24 hours\n\n  private constructor() {\n    const homeDir = process.env.HOME || process.env.USERPROFILE || '';\n    this.sessionsDir = path.join(homeDir, '.stackmemory', 'sessions');\n  }\n\n  static getInstance(): SessionManager {\n    if (!SessionManager.instance) {\n      SessionManager.instance = new SessionManager();\n    }\n    return SessionManager.instance;\n  }\n\n  async initialize(): Promise<void> {\n    try {\n      await fs.mkdir(this.sessionsDir, { recursive: true });\n      await fs.mkdir(path.join(this.sessionsDir, 'projects'), { recursive: true });\n      await fs.mkdir(path.join(this.sessionsDir, 'history'), { recursive: true });\n    } catch (error) {\n      throw new SystemError(\n        'Failed to initialize session directories',\n        ErrorCode.INITIALIZATION_ERROR,\n        { error, sessionsDir: this.sessionsDir }\n      );\n    }\n  }\n\n  async getOrCreateSession(options?: SessionOptions): Promise<Session> {\n    // 1. Check explicit session ID\n    if (options?.sessionId) {\n      const session = await this.loadSession(options.sessionId);\n      if (session) {\n        this.currentSession = session;\n        return session;\n      }\n    }\n\n    // 2. Check environment variable\n    const envSessionId = process.env.STACKMEMORY_SESSION;\n    if (envSessionId) {\n      const session = await this.loadSession(envSessionId);\n      if (session) {\n        this.currentSession = session;\n        return session;\n      }\n    }\n\n    // 3. Check project + branch context\n    const projectHash = await this.getProjectHash(options?.projectPath);\n    const branch = options?.branch || await this.getGitBranch(options?.projectPath);\n\n    if (projectHash) {\n      // Try project+branch session\n      const branchSession = await this.findProjectBranchSession(projectHash, branch);\n      if (branchSession && this.isSessionRecent(branchSession)) {\n        await this.touchSession(branchSession);\n        this.currentSession = branchSession;\n        return branchSession;\n      }\n\n      // Try last active for project\n      const lastActive = await this.findLastActiveSession(projectHash);\n      if (lastActive && this.isSessionRecent(lastActive)) {\n        await this.touchSession(lastActive);\n        this.currentSession = lastActive;\n        return lastActive;\n      }\n    }\n\n    // 4. Create new session\n    const newSession = await this.createSession({\n      projectId: projectHash || 'global',\n      branch,\n      metadata: options?.metadata\n    });\n    \n    this.currentSession = newSession;\n    return newSession;\n  }\n\n  async createSession(params: {\n    projectId: string;\n    branch?: string;\n    metadata?: Session['metadata'];\n  }): Promise<Session> {\n    const session: Session = {\n      sessionId: uuidv4(),\n      runId: uuidv4(),\n      projectId: params.projectId,\n      branch: params.branch,\n      startedAt: Date.now(),\n      lastActiveAt: Date.now(),\n      metadata: {\n        ...params.metadata,\n        user: process.env.USER,\n        environment: process.env.NODE_ENV || 'development',\n        cliVersion: process.env.npm_package_version\n      },\n      state: 'active'\n    };\n\n    await this.saveSession(session);\n    await this.setProjectActiveSession(params.projectId, session.sessionId);\n    \n    // Set as current session\n    this.currentSession = session;\n    \n    logger.info('Created new session', {\n      sessionId: session.sessionId,\n      projectId: session.projectId,\n      branch: session.branch\n    });\n\n    return session;\n  }\n\n  async loadSession(sessionId: string): Promise<Session | null> {\n    try {\n      const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);\n      const data = await fs.readFile(sessionPath, 'utf-8');\n      return JSON.parse(data) as Session;\n    } catch (error) {\n      // Check history\n      try {\n        const historyPath = path.join(this.sessionsDir, 'history', `${sessionId}.json`);\n        const data = await fs.readFile(historyPath, 'utf-8');\n        return JSON.parse(data) as Session;\n      } catch {\n        return null;\n      }\n    }\n  }\n\n  async saveSession(session: Session): Promise<void> {\n    const sessionPath = path.join(this.sessionsDir, `${session.sessionId}.json`);\n    await fs.writeFile(sessionPath, JSON.stringify(session, null, 2));\n  }\n\n  async suspendSession(sessionId?: string): Promise<void> {\n    const id = sessionId || this.currentSession?.sessionId;\n    if (!id) return;\n\n    const session = await this.loadSession(id);\n    if (session) {\n      session.state = 'suspended';\n      session.lastActiveAt = Date.now();\n      await this.saveSession(session);\n    }\n  }\n\n  async resumeSession(sessionId: string): Promise<Session> {\n    const session = await this.loadSession(sessionId);\n    if (!session) {\n      throw new SystemError(\n        'Session not found',\n        ErrorCode.NOT_FOUND,\n        { sessionId }\n      );\n    }\n\n    session.state = 'active';\n    session.lastActiveAt = Date.now();\n    await this.saveSession(session);\n    \n    this.currentSession = session;\n    return session;\n  }\n\n  async closeSession(sessionId?: string): Promise<void> {\n    const id = sessionId || this.currentSession?.sessionId;\n    if (!id) return;\n\n    const session = await this.loadSession(id);\n    if (session) {\n      session.state = 'closed';\n      session.lastActiveAt = Date.now();\n      \n      // Move to history\n      const sessionPath = path.join(this.sessionsDir, `${session.sessionId}.json`);\n      const historyPath = path.join(this.sessionsDir, 'history', `${session.sessionId}.json`);\n      \n      await fs.rename(sessionPath, historyPath);\n    }\n  }\n\n  async listSessions(filter?: {\n    projectId?: string;\n    state?: Session['state'];\n    branch?: string;\n  }): Promise<Session[]> {\n    const sessions: Session[] = [];\n    \n    // Load active sessions\n    const files = await fs.readdir(this.sessionsDir);\n    for (const file of files) {\n      if (file.endsWith('.json')) {\n        const session = await this.loadSession(file.replace('.json', ''));\n        if (session) {\n          sessions.push(session);\n        }\n      }\n    }\n\n    // Apply filters\n    return sessions.filter(s => {\n      if (filter?.projectId && s.projectId !== filter.projectId) return false;\n      if (filter?.state && s.state !== filter.state) return false;\n      if (filter?.branch && s.branch !== filter.branch) return false;\n      return true;\n    });\n  }\n\n  async mergeSessions(sourceId: string, targetId: string): Promise<Session> {\n    const source = await this.loadSession(sourceId);\n    const target = await this.loadSession(targetId);\n\n    if (!source || !target) {\n      throw new SystemError(\n        'Session not found for merge',\n        ErrorCode.NOT_FOUND,\n        { sourceId, targetId }\n      );\n    }\n\n    // Merge metadata\n    target.metadata = {\n      ...target.metadata,\n      ...source.metadata,\n      tags: [...(target.metadata.tags || []), ...(source.metadata.tags || [])]\n    };\n\n    // Update timestamps\n    target.lastActiveAt = Date.now();\n\n    // Close source session\n    await this.closeSession(sourceId);\n    await this.saveSession(target);\n\n    logger.info('Merged sessions', {\n      source: sourceId,\n      target: targetId\n    });\n\n    return target;\n  }\n\n  async cleanupStaleSessions(maxAge: number = 30 * 24 * 60 * 60 * 1000): Promise<number> {\n    const historyDir = path.join(this.sessionsDir, 'history');\n    const files = await fs.readdir(historyDir);\n    const cutoff = Date.now() - maxAge;\n    let cleaned = 0;\n\n    for (const file of files) {\n      if (file.endsWith('.json')) {\n        const filePath = path.join(historyDir, file);\n        const stats = await fs.stat(filePath);\n        \n        if (stats.mtimeMs < cutoff) {\n          await fs.unlink(filePath);\n          cleaned++;\n        }\n      }\n    }\n\n    logger.info(`Cleaned up ${cleaned} stale sessions`);\n    return cleaned;\n  }\n\n  getCurrentSession(): Session | null {\n    return this.currentSession;\n  }\n\n  getSessionRunId(): string {\n    return this.currentSession?.runId || uuidv4();\n  }\n\n  private async getProjectHash(projectPath?: string): Promise<string | null> {\n    try {\n      const cwd = projectPath || process.cwd();\n      \n      // Try to use the basename of the directory as project ID\n      const path = await import('path');\n      const projectName = path.basename(cwd);\n      \n      // Check if it looks like a demo/development project\n      if (projectName === 'stackmemory') {\n        return 'stackmemory-demo';\n      }\n      \n      // Otherwise use hash for consistency\n      const hash = crypto.createHash('sha256');\n      hash.update(cwd);\n      return hash.digest('hex').substring(0, 12);\n    } catch {\n      return null;\n    }\n  }\n\n  private async getGitBranch(projectPath?: string): Promise<string | undefined> {\n    try {\n      const { execSync } = await import('child_process');\n      const cwd = projectPath || process.cwd();\n      const branch = execSync('git rev-parse --abbrev-ref HEAD', {\n        cwd,\n        encoding: 'utf-8'\n      }).trim();\n      return branch;\n    } catch {\n      return undefined;\n    }\n  }\n\n  private async findProjectBranchSession(\n    projectHash: string, \n    branch?: string\n  ): Promise<Session | null> {\n    if (!branch) return null;\n\n    const sessions = await this.listSessions({\n      projectId: projectHash,\n      state: 'active',\n      branch\n    });\n\n    return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0] || null;\n  }\n\n  private async findLastActiveSession(projectHash: string): Promise<Session | null> {\n    const sessions = await this.listSessions({\n      projectId: projectHash,\n      state: 'active'\n    });\n\n    return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0] || null;\n  }\n\n  private async setProjectActiveSession(projectId: string, sessionId: string): Promise<void> {\n    const projectFile = path.join(this.sessionsDir, 'projects', `${projectId}.json`);\n    await fs.writeFile(projectFile, JSON.stringify({\n      projectId,\n      activeSessionId: sessionId,\n      updatedAt: Date.now()\n    }, null, 2));\n  }\n\n  private isSessionRecent(session: Session): boolean {\n    return Date.now() - session.lastActiveAt < this.STALE_THRESHOLD;\n  }\n\n  private async touchSession(session: Session): Promise<void> {\n    session.lastActiveAt = Date.now();\n    await this.saveSession(session);\n  }\n}\n\nexport const sessionManager = SessionManager.getInstance();"],
+  "mappings": "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",
+  "names": ["FrameQueryMode", "path"]
+}

package/dist/core/trace/cli-trace-wrapper.js

@@ -0,0 +1,110 @@
+import { trace } from "./debug-trace.js";
+import { logger } from "../monitoring/logger.js";
+function wrapCommand(command) {
+  const originalAction = command.action.bind(command);
+  command.action(async function(...args) {
+    const commandPath = getCommandPath(command);
+    const options = args[args.length - 1];
+    const commandArgs = args.slice(0, -1);
+    const context = {
+      command: commandPath,
+      args: commandArgs,
+      options: typeof options === "object" ? options : {},
+      cwd: process.cwd(),
+      env: {
+        NODE_ENV: process.env.NODE_ENV,
+        DEBUG_TRACE: process.env.DEBUG_TRACE,
+        LINEAR_API_KEY: process.env.LINEAR_API_KEY ? "[SET]" : "[NOT SET]"
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    logger.info(`CLI Command: ${commandPath}`, context);
+    await trace.command(commandPath, context, async () => {
+      try {
+        const result = await originalAction.apply(null, args);
+        logger.info(`CLI Command Completed: ${commandPath}`, {
+          duration: trace.exportTraces().find((t) => t.name === commandPath)?.duration
+        });
+        if (process.env.DEBUG_TRACE === "true") {
+          console.log(trace.getExecutionSummary());
+        }
+      } catch (error) {
+        logger.error(`CLI Command Failed: ${commandPath}`, error, context);
+        const lastError = trace.getLastError();
+        if (lastError) {
+          console.error("\n\u{1F4CD} Error occurred at:");
+          console.error(`   ${lastError.name}`);
+          if (lastError.params) {
+            console.error("   With params:", JSON.stringify(lastError.params, null, 2));
+          }
+          console.error("   Error details:", lastError.error);
+        }
+        throw error;
+      }
+    });
+  });
+  command.commands.forEach((subcommand) => {
+    wrapCommand(subcommand);
+  });
+  return command;
+}
+function getCommandPath(command) {
+  const parts = [];
+  let current = command;
+  while (current) {
+    if (current.name()) {
+      parts.unshift(current.name());
+    }
+    current = current.parent;
+  }
+  return parts.join(" ");
+}
+function wrapProgram(program) {
+  program.exitOverride((err) => {
+    if (err.code === "commander.help" || err.code === "commander.version") {
+      process.exit(0);
+    }
+    logger.error("CLI Error", err, {
+      code: err.code,
+      exitCode: err.exitCode,
+      command: process.argv.slice(2).join(" ")
+    });
+    if (process.env.DEBUG_TRACE === "true") {
+      console.error("\n" + trace.getExecutionSummary());
+    }
+    process.exit(err.exitCode || 1);
+  });
+  program.hook("preAction", (thisCommand) => {
+    trace.reset();
+    const commandPath = getCommandPath(thisCommand);
+    logger.debug(`Preparing to execute: ${commandPath}`, {
+      args: thisCommand.args,
+      opts: thisCommand.opts()
+    });
+  });
+  program.hook("postAction", (thisCommand) => {
+    const commandPath = getCommandPath(thisCommand);
+    logger.debug(`Completed execution: ${commandPath}`);
+  });
+  program.commands.forEach((command) => {
+    wrapCommand(command);
+  });
+  return program;
+}
+function traceStep(name, fn) {
+  return trace.step(name, fn);
+}
+function traceQuery(sql, params, fn) {
+  return trace.traceSync("query", sql.substring(0, 100), params, fn);
+}
+function traceAPI(method, url, body, fn) {
+  return trace.api(method, url, body, fn);
+}
+export {
+  traceAPI,
+  traceQuery,
+  traceStep,
+  wrapCommand,
+  wrapProgram
+};
+//# sourceMappingURL=cli-trace-wrapper.js.map

package/dist/core/trace/cli-trace-wrapper.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/core/trace/cli-trace-wrapper.ts"],
+  "sourcesContent": ["/**\n * CLI Command Trace Wrapper\n * Automatically wraps Commander.js commands with comprehensive tracing\n */\n\nimport { Command } from 'commander';\nimport { trace } from './debug-trace.js';\nimport { logger } from '../monitoring/logger.js';\n\nexport function wrapCommand(command: Command): Command {\n  const originalAction = command.action.bind(command);\n  \n  command.action(async function(...args: any[]): Promise<void> {\n    // Extract command path and options\n    const commandPath = getCommandPath(command);\n    const options = args[args.length - 1];\n    const commandArgs = args.slice(0, -1);\n    \n    // Build comprehensive context\n    const context = {\n      command: commandPath,\n      args: commandArgs,\n      options: typeof options === 'object' ? options : {},\n      cwd: process.cwd(),\n      env: {\n        NODE_ENV: process.env.NODE_ENV,\n        DEBUG_TRACE: process.env.DEBUG_TRACE,\n        LINEAR_API_KEY: process.env.LINEAR_API_KEY ? '[SET]' : '[NOT SET]',\n      },\n      timestamp: new Date().toISOString(),\n    };\n    \n    // Log command start\n    logger.info(`CLI Command: ${commandPath}`, context);\n    \n    // Wrap the actual action with tracing\n    await trace.command(commandPath, context, async () => {\n      try {\n        // Call the original action with wrapped handler\n        const result = await originalAction.apply(null, args as any);\n        \n        // Log successful completion\n        logger.info(`CLI Command Completed: ${commandPath}`, {\n          duration: trace.exportTraces().find(t => t.name === commandPath)?.duration,\n        });\n        \n        // Show execution summary if verbose\n        if (process.env.DEBUG_TRACE === 'true') {\n          console.log(trace.getExecutionSummary());\n        }\n      } catch (error) {\n        // Enhanced error logging for CLI commands\n        logger.error(`CLI Command Failed: ${commandPath}`, error as Error, context);\n        \n        // Get the last error trace for debugging\n        const lastError = trace.getLastError();\n        if (lastError) {\n          console.error('\\n\uD83D\uDCCD Error occurred at:');\n          console.error(`   ${lastError.name}`);\n          if (lastError.params) {\n            console.error('   With params:', JSON.stringify(lastError.params, null, 2));\n          }\n          console.error('   Error details:', lastError.error);\n        }\n        \n        // Re-throw to maintain original error handling\n        throw error;\n      }\n    });\n  });\n  \n  // Recursively wrap subcommands\n  command.commands.forEach(subcommand => {\n    wrapCommand(subcommand);\n  });\n  \n  return command;\n}\n\nfunction getCommandPath(command: Command): string {\n  const parts: string[] = [];\n  let current: Command | null = command;\n  \n  while (current) {\n    if (current.name()) {\n      parts.unshift(current.name());\n    }\n    current = current.parent as Command | null;\n  }\n  \n  return parts.join(' ');\n}\n\n/**\n * Wrap the main program with comprehensive tracing\n */\nexport function wrapProgram(program: Command): Command {\n  // Add global error handler with tracing\n  program.exitOverride((err) => {\n    if (err.code === 'commander.help' || err.code === 'commander.version') {\n      // Normal help/version display, not an error\n      process.exit(0);\n    }\n    \n    // Log the error with full context\n    logger.error('CLI Error', err, {\n      code: err.code,\n      exitCode: err.exitCode,\n      command: process.argv.slice(2).join(' '),\n    });\n    \n    // Show trace summary on error\n    if (process.env.DEBUG_TRACE === 'true') {\n      console.error('\\n' + trace.getExecutionSummary());\n    }\n    \n    process.exit(err.exitCode || 1);\n  });\n  \n  // Add pre-action hook for setup\n  program.hook('preAction', (thisCommand) => {\n    // Initialize trace context for this command\n    trace.reset();\n    \n    // Log command invocation\n    const commandPath = getCommandPath(thisCommand);\n    logger.debug(`Preparing to execute: ${commandPath}`, {\n      args: thisCommand.args,\n      opts: thisCommand.opts(),\n    });\n  });\n  \n  // Add post-action hook for cleanup\n  program.hook('postAction', (thisCommand) => {\n    // Log completion\n    const commandPath = getCommandPath(thisCommand);\n    logger.debug(`Completed execution: ${commandPath}`);\n  });\n  \n  // Wrap all existing commands\n  program.commands.forEach(command => {\n    wrapCommand(command);\n  });\n  \n  return program;\n}\n\n/**\n * Helper to wrap async functions with step tracing\n */\nexport function traceStep<T>(name: string, fn: () => Promise<T>): Promise<T> {\n  return trace.step(name, fn);\n}\n\n/**\n * Helper to wrap database queries\n */\nexport function traceQuery<T>(sql: string, params: any, fn: () => T): T {\n  return trace.traceSync('query', sql.substring(0, 100), params, fn);\n}\n\n/**\n * Helper to wrap API calls\n */\nexport function traceAPI<T>(\n  method: string,\n  url: string,\n  body: any,\n  fn: () => Promise<T>\n): Promise<T> {\n  return trace.api(method, url, body, fn);\n}"],
+  "mappings": "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",
+  "names": []
+}