@vfarcic/dot-ai 0.116.0 → 0.118.0

package/README.md

@@ -4,143 +4,81 @@
 
 ![DevOps AI Toolkit Logo](assets/images/logo.png)
 
+[![npm version](https://badge.fury.io/js/%40vfarcic%2Fdot-ai.svg)](https://www.npmjs.com/package/@vfarcic/dot-ai)
+[![npm downloads](https://img.shields.io/npm/dm/@vfarcic/dot-ai.svg)](https://www.npmjs.com/package/@vfarcic/dot-ai)
+[![GitHub release](https://img.shields.io/github/release/vfarcic/dot-ai.svg)](https://github.com/vfarcic/dot-ai/releases/latest)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Project Status](https://img.shields.io/badge/status-beta-orange)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/vfarcic/dot-ai/badge)](https://scorecard.dev/viewer/?uri=github.com/vfarcic/dot-ai)
+[![GitHub stars](https://img.shields.io/github/stars/vfarcic/dot-ai.svg?style=social&label=Star)](https://github.com/vfarcic/dot-ai)
+
 </div>
 
-DevOps AI Toolkit is an AI-powered development productivity platform that enhances software development workflows through intelligent automation and AI-driven assistance.
+**AI-powered platform engineering and DevOps automation through intelligent Kubernetes operations and conversational workflows.**
 
 📚 [Quick Start](./docs/quick-start.md) | 🔧 [MCP Setup](./docs/mcp-setup.md) | 🛠️ [Features & Tools](./docs/mcp-tools-overview.md)
 
-## Who is this for?
-
-### Kubernetes Deployment
-- **Developers**: Deploy applications without needing deep Kubernetes expertise
-- **Platform Engineers**: Create organizational deployment patterns that enhance AI recommendations with institutional knowledge and best practices, and scan cluster resources to enable semantic matching for dramatically improved recommendation accuracy
-- **Security Engineers**: Define governance policies that integrate into deployment workflows with optional Kyverno enforcement
-
-### Kubernetes Issue Remediation
-- **DevOps Engineers**: Quickly diagnose and fix Kubernetes issues without deep troubleshooting expertise
-- **SRE Teams**: Automate root cause analysis and generate executable remediation commands
-- **Support Teams**: Handle incident response with AI-guided investigation and repair workflows
-
-<!--
-### Platform Building
-DEVELOPER NOTE: This tool is under active development with incomplete functionality. Not recommended for production use.
-- **Platform Engineers**: Install and configure platform tools conversationally without memorizing script paths and commands
-- **New Team Members**: Build platform infrastructure through zero-knowledge guided workflows
-- **DevOps Teams**: Create and manage Kubernetes clusters through natural language interactions
--->
-
-### Documentation Testing  
-- **Documentation Maintainers**: Automatically validate documentation accuracy and catch outdated content
-- **Technical Writers**: Identify which sections need updates and prioritize work effectively
-- **Open Source Maintainers**: Ensure documentation works correctly for new contributors
+---
 
-### Shared Prompts Library
-- **Development Teams**: Share proven prompts across projects without file management
-- **Project Managers**: Standardize workflows with consistent prompt usage across teams
-- **Individual Developers**: Access curated prompt library via native slash commands
+## What is DevOps AI Toolkit?
 
-### AI Integration
-- **AI Agents**: Integrate all capabilities with Claude Code, Cursor, or VS Code for conversational workflows
-- **REST API**: Access all tools via standard HTTP endpoints for CI/CD pipelines, automation scripts, and traditional applications
+DevOps AI Toolkit brings AI-powered intelligence to platform engineering, Kubernetes operations, and development workflows. It provides intelligent Kubernetes deployment recommendations through capability discovery and semantic matching, AI-powered issue remediation, automated repository setup with governance and security files, and shared prompt libraries for consistent development workflows—all through natural language conversation.
 
-## Key Features
+Built on the Model Context Protocol (MCP), it integrates seamlessly with Claude Code, Cursor, and VS Code to provide conversational interaction for complex DevOps and development tasks.
 
-### Kubernetes Deployment Intelligence
-🔍 **Smart Discovery**: Automatically finds all available resources and operators in your cluster  
-🧠 **Semantic Capability Management**: Discovers what each resource actually does for intelligent matching  
-🤖 **AI Recommendations**: Smart intent clarification gathers missing context, then provides deployment suggestions tailored to your specific cluster setup with enhanced semantic understanding  
-🔧 **Operator-Aware**: Leverages custom operators and CRDs when available  
-🚀 **Complete Workflow**: From discovery to deployment with automated Kubernetes integration
+## Mission
 
-📖 [Learn more →](./docs/mcp-recommendation-guide.md)
+DevOps AI Toolkit democratizes platform engineering and cloud native operations by making complex workflows accessible through AI-powered automation. We eliminate the expertise barrier that prevents teams from adopting best practices in Kubernetes operations, repository governance, and standardized development workflows—making professional-grade DevOps accessible through natural language interaction.
 
-#### Capability-Enhanced Recommendations
-Transform how AI understands your cluster by discovering semantic capabilities of each resource:
+## Who Should Use This?
 
-**The Problem**: Traditional discovery sees `sqls.devopstoolkit.live` as a meaningless name among hundreds of resources.
+**DevOps AI Toolkit is for teams who want to**:
+- Manage cloud resources (AWS, Azure, GCP) using Kubernetes as a control plane (developers, platform engineers)
+- Quickly diagnose and fix cluster and infrastructure issues (SREs, DevOps engineers)
+- Standardize resource provisioning with organizational patterns and policies (security engineers, platform teams)
+- Bootstrap repositories with governance and security files (project maintainers)
+- Access curated development prompts through native slash commands (development teams)
 
-**The Solution**: Capability management teaches the system that `sqls.devopstoolkit.live` handles PostgreSQL databases with multi-cloud support.
+## Scope
 
-**Before Capability Management:**
-```
-User: "I need a PostgreSQL database"
-AI: Gets 400+ generic resource names → picks complex multi-resource solution
-Result: Misses optimal single-resource solutions
-```
+### In Scope
+- AI-powered resource provisioning recommendations using Kubernetes as control plane
+- Intelligent issue remediation and root cause analysis
+- Organizational pattern and policy management with semantic search
+- MCP-based integration with AI coding assistants
+- Multi-provider AI model support (Claude, GPT, Gemini)
+- Project setup with governance, legal, and security files
 
-**After Capability Management:**
-```
-User: "I need a PostgreSQL database"  
-AI: Gets pre-filtered relevant resources with rich context
-Result: Finds sqls.devopstoolkit.live as perfect match ✨
-```
+### Out of Scope
+- Kubernetes cluster provisioning/management (delegates to existing tools)
+- CI/CD pipeline execution (provides recommendations only)
+- Application runtime monitoring (integrates with existing observability tools)
 
-📖 [Learn more →](./docs/mcp-capability-management-guide.md)
+## Key Features
 
-### Kubernetes Issue Remediation
-🔍 **AI-Powered Root Cause Analysis**: Multi-step investigation loop identifies the real cause behind Kubernetes failures  
-🛠️ **Executable Remediation**: Generates specific kubectl commands with risk assessment and validation  
-⚡ **Dual Execution Modes**: Manual approval workflow or automatic execution based on confidence thresholds  
-🔒 **Safety Mechanisms**: Automatic fallback to manual mode when validation discovers additional issues  
-🎯 **Cross-Resource Intelligence**: Understands how pod issues may require fixes in different resource types (storage, networking, etc.)
+### 🔍 Resource Provisioning Intelligence
+Automatically discovers cluster resources using semantic capability management. AI understands what each resource actually does, providing intelligent recommendations for provisioning resources across clouds using Kubernetes as a control plane.
+📖 [Deployment Guide](./docs/mcp-recommendation-guide.md) | [Capability Management](./docs/mcp-capability-management-guide.md)
 
+### 🛠️ Issue Remediation
+AI-powered root cause analysis with multi-step investigation, executable remediation commands, and safety mechanisms for manual or automatic execution.
 📖 [Learn more →](./docs/mcp-remediate-guide.md)
 
-<!--
-### Platform Building
-DEVELOPER NOTE: This tool is under active development with incomplete functionality. Not recommended for production use.
-🗣️ **Natural Language Operations**: Install tools and create clusters through conversation without memorizing commands
-🔍 **Dynamic Discovery**: Automatically discovers 21+ available platform operations from infrastructure scripts
-🤖 **AI-Powered Intent Mapping**: Understands variations like "Install Argo CD", "Set up ArgoCD", "Deploy Argo CD"
-💬 **Conversational Configuration**: Guides through parameter collection step-by-step with sensible defaults
-🎯 **Zero-Knowledge Onboarding**: New users successfully build platforms without documentation
-
-📖 [Learn more →](./docs/mcp-build-platform-guide.md)
--->
-
-### Documentation Testing & Validation
-📖 **Automated Testing**: Validates documentation by executing commands and testing examples  
-🔍 **Two-Phase Validation**: Tests both functionality (does it work?) and semantic accuracy (are descriptions truthful?)  
-🛠️ **Fix Application**: User-driven selection and application of recommended documentation improvements  
-💾 **Session Management**: Resumable testing workflows for large documentation sets
-
-📖 [Learn more →](./docs/mcp-documentation-testing-guide.md)
-
-### Organizational Pattern Management
-🏛️ **Pattern Creation**: Define organizational deployment patterns that capture institutional knowledge  
-🧠 **AI Enhancement**: Patterns automatically enhance deployment recommendations with organizational context  
-🔍 **Semantic Search**: Uses Vector DB (Qdrant) for intelligent pattern matching based on user intent  
-📋 **Best Practices**: Share deployment standards across teams through reusable patterns
-
-📖 [Learn more →](./docs/pattern-management-guide.md)
-
-### Policy Management & Governance
-🛡️ **Policy Creation**: Define governance policies that guide users toward compliant configurations  
-⚠️ **Compliance Integration**: Policies create required questions with compliance indicators during deployment  
-🤖 **Kyverno Generation**: Automatically generates Kyverno ClusterPolicies for active enforcement  
-🎯 **Proactive Governance**: Prevents configuration drift by embedding compliance into the recommendation workflow  
-🔍 **Vector Storage**: Uses Qdrant Vector DB for semantic policy matching and retrieval
-
-📖 [Learn more →](./docs/policy-management-guide.md)
-
-### Shared Prompts Library
-🎯 **Native Slash Commands**: Prompts appear as `/dot-ai:prompt-name` in your coding agent  
-📚 **Curated Library**: Access proven prompts for code review, documentation, architecture, and project management  
-🔄 **Zero Setup**: Connect to MCP server and prompts are immediately available across all projects  
-🤝 **Team Consistency**: Standardized prompt usage with centralized management
-
-📖 [Learn more →](./docs/mcp-prompts-guide.md)
+### 🏛️ Pattern & Policy Management
+Capture organizational knowledge and governance policies that automatically enhance AI recommendations with best practices and compliance requirements. Uses vector search for intelligent semantic matching.
+📖 [Pattern Management](./docs/pattern-management-guide.md) | [Policy Management](./docs/policy-management-guide.md)
 
-### AI Integration
-⚡ **MCP Integration**: Works seamlessly with Claude Code, Cursor, or VS Code through Model Context Protocol  
-🤖 **Conversational Interface**: Natural language interaction for deployment, documentation testing, pattern management, and shared prompt workflows
+### 📦 Project Setup & Governance
+Generate 25+ governance, legal, and automation files (LICENSE, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, GitHub workflows, Renovate, OpenSSF Scorecard) for repository standardization.
+📖 [Learn more →](./docs/mcp-project-setup-guide.md)
 
-**Setup Required**: See the [MCP Setup Guide](./docs/mcp-setup.md) for complete configuration instructions.
+### 💬 Shared Prompts Library
+Access curated prompts as native slash commands (`/dot-ai:prompt-name`) in your coding agent for consistent workflows across projects.
+📖 [Learn more →](./docs/mcp-prompts-guide.md)
 
----
-🚀 **Ready to deploy?** Jump to the [Quick Start](./docs/quick-start.md) guide to begin using DevOps AI Toolkit.
----
+### ⚡ AI Integration
+Works with Claude Code, Cursor, VS Code via Model Context Protocol. Supports multiple AI providers (Claude, GPT, Gemini) for flexibility and cost optimization.
+📖 [AI Model Configuration](./docs/mcp-setup.md#ai-model-configuration)
 
 ## See It In Action
 
@@ -148,42 +86,58 @@ DEVELOPER NOTE: This tool is under active development with incomplete functional
 
 This video explains the platform engineering problem and demonstrates the Kubernetes deployment recommendation workflow from intent to running applications.
 
-## Documentation
-
-### 🚀 Getting Started
-- **[MCP Setup Guide](docs/mcp-setup.md)** - Complete configuration instructions for AI tools integration
-- **[Tools and Features Overview](docs/mcp-tools-overview.md)** - Comprehensive guide to all available tools and features
+## Quick Start
 
-## Troubleshooting
+Get started in 3 steps:
+1. Configure MCP server (Docker or npm)
+2. Connect your AI coding assistant (Claude Code, Cursor, VS Code)
+3. Start using conversational workflows
 
-### MCP Issues
+## Documentation
 
-**MCP server won't start:**
-- Verify environment variables are correctly configured in `.mcp.json` env section
-- Check session directory exists and is writable
-- Ensure `ANTHROPIC_API_KEY` is valid
+### Getting Started
+- **[Quick Start Guide](docs/quick-start.md)** - Get started in minutes
+- **[MCP Setup Guide](docs/mcp-setup.md)** - Complete configuration instructions
+- **[Tools Overview](docs/mcp-tools-overview.md)** - All available tools and features
 
-**"No active cluster" errors:**
-- Verify kubectl connectivity: `kubectl cluster-info`
-- Check KUBECONFIG path in environment variables
-- Test cluster access: `kubectl get nodes`
+### Feature Guides
+- **[Resource Provisioning](docs/mcp-recommendation-guide.md)** - AI-powered deployment recommendations
+- **[Capability Management](docs/mcp-capability-management-guide.md)** - Semantic resource discovery
+- **[Issue Remediation](docs/mcp-remediate-guide.md)** - AI-powered troubleshooting
+- **[Pattern Management](docs/pattern-management-guide.md)** - Organizational deployment patterns
+- **[Policy Management](docs/policy-management-guide.md)** - Governance and compliance
+- **[Project Setup](docs/mcp-project-setup-guide.md)** - Repository governance automation
 
 ## Support
 
-- **Issues**: [GitHub Issues](https://github.com/vfarcic/dot-ai/issues)
+- **[Support Guide](SUPPORT.md)** - How to get help and where to ask questions
+- **GitHub Issues**: [Bug reports and feature requests](https://github.com/vfarcic/dot-ai/issues)
+- **GitHub Discussions**: [Community Q&A and discussions](https://github.com/vfarcic/dot-ai/discussions)
+- **Troubleshooting**: See [Troubleshooting Guide](./docs/mcp-setup.md#troubleshooting) for common problems
+
+## Contributing & Governance
 
-## Contributing
+We welcome contributions from the community! Please review:
 
-We welcome contributions! Please:
-- Fork the repository and create a feature branch
-- Run integration tests to ensure changes work correctly (see [Integration Testing Guide](docs/integration-testing-guide.md))
-- Follow existing code style and conventions
-- Submit a pull request with a clear description of changes
+- **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute code, docs, and ideas
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards and expectations
+- **[Security Policy](SECURITY.md)** - How to report security vulnerabilities
+- **[Governance](docs/GOVERNANCE.md)** - Project governance and decision-making
+- **[Maintainers](docs/MAINTAINERS.md)** - Current project maintainers
+- **[Roadmap](docs/ROADMAP.md)** - Project direction and priorities
 
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
+## Acknowledgments
+
+DevOps AI Toolkit is built on:
+- [Model Context Protocol](https://modelcontextprotocol.io/) for AI integration framework
+- [Vercel AI SDK](https://sdk.vercel.ai/) for unified AI provider interface
+- [Kubernetes](https://kubernetes.io/) for the cloud native foundation
+- [CNCF](https://www.cncf.io/) for the cloud native ecosystem
+
 ---
 
-**DevOps AI Toolkit** - AI-powered development productivity platform for enhanced software development workflows.
+**DevOps AI Toolkit** - Making cloud native operations accessible through AI-powered intelligence.

package/dist/core/ai-provider-factory.d.ts

@@ -38,12 +38,14 @@ export declare class AIProviderFactory {
      * Detects provider from AI_PROVIDER env var (defaults to 'anthropic')
      * and loads corresponding API key from environment.
      *
+     * If no API keys are configured, returns a NoOpAIProvider that allows
+     * the MCP server to start but returns helpful errors when AI is needed.
+     *
      * Supports AI_PROVIDER_SDK env var to override SDK choice:
      * - 'native' (default): Use native provider SDK
      * - 'vercel': Use Vercel AI SDK for the provider
      *
-     * @returns Configured AI provider instance
-     * @throws Error if required environment variables are missing
+     * @returns Configured AI provider instance or NoOpProvider if no keys available
      */
     static createFromEnv(): AIProvider;
     /**

package/dist/core/ai-provider-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-provider-factory.d.ts","sourceRoot":"","sources":["../../src/core/ai-provider-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,UAAU,EACV,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AA8BjC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU;IAgCnD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,aAAa,IAAI,UAAU;IA+ClC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAItC;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMrD;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,IAAI,MAAM,EAAE;IAMxC;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAGxD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAE7C"}
+{"version":3,"file":"ai-provider-factory.d.ts","sourceRoot":"","sources":["../../src/core/ai-provider-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,UAAU,EACV,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AA+BjC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU;IAgCnD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,aAAa,IAAI,UAAU;IA2DlC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAItC;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMrD;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,IAAI,MAAM,EAAE;IAMxC;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAGxD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAE7C"}

package/dist/core/ai-provider-factory.js

@@ -13,6 +13,7 @@ exports.AIProviderFactory = void 0;
 exports.createAIProvider = createAIProvider;
 const anthropic_provider_1 = require("./providers/anthropic-provider");
 const vercel_provider_1 = require("./providers/vercel-provider");
+const noop_provider_1 = require("./providers/noop-provider");
 const model_config_1 = require("./model-config");
 /**
  * Provider environment variable mappings
@@ -86,29 +87,39 @@ class AIProviderFactory {
      * Detects provider from AI_PROVIDER env var (defaults to 'anthropic')
      * and loads corresponding API key from environment.
      *
+     * If no API keys are configured, returns a NoOpAIProvider that allows
+     * the MCP server to start but returns helpful errors when AI is needed.
+     *
      * Supports AI_PROVIDER_SDK env var to override SDK choice:
      * - 'native' (default): Use native provider SDK
      * - 'vercel': Use Vercel AI SDK for the provider
      *
-     * @returns Configured AI provider instance
-     * @throws Error if required environment variables are missing
+     * @returns Configured AI provider instance or NoOpProvider if no keys available
      */
     static createFromEnv() {
         const providerType = process.env.AI_PROVIDER || 'anthropic';
         const sdkPreference = process.env.AI_PROVIDER_SDK || 'native';
         // Validate provider is implemented
         if (!IMPLEMENTED_PROVIDERS.includes(providerType)) {
-            throw new Error(`Invalid AI_PROVIDER: ${providerType}. ` +
-                `Must be one of: ${IMPLEMENTED_PROVIDERS.join(', ')}`);
+            // Write to stderr for logging
+            process.stderr.write(`WARNING: Invalid AI_PROVIDER: ${providerType}. ` +
+                `Must be one of: ${IMPLEMENTED_PROVIDERS.join(', ')}. ` +
+                `Falling back to NoOpProvider.\n`);
+            return new noop_provider_1.NoOpAIProvider();
         }
         // Get API key for the provider
         const apiKeyEnvVar = PROVIDER_ENV_KEYS[providerType];
         if (!apiKeyEnvVar) {
-            throw new Error(`No API key environment variable defined for provider: ${providerType}`);
+            process.stderr.write(`WARNING: No API key environment variable defined for provider: ${providerType}. ` +
+                `Falling back to NoOpProvider.\n`);
+            return new noop_provider_1.NoOpAIProvider();
         }
         const apiKey = process.env[apiKeyEnvVar];
         if (!apiKey) {
-            throw new Error(`${apiKeyEnvVar} environment variable must be set for ${providerType} provider`);
+            process.stderr.write(`INFO: ${apiKeyEnvVar} not configured. ` +
+                `AI features will be unavailable. ` +
+                `Tools that don't require AI (prompts, project-setup) will still work.\n`);
+            return new noop_provider_1.NoOpAIProvider();
         }
         // Get optional model override
         const model = process.env.AI_MODEL;

package/dist/core/capability-operations.js

@@ -346,7 +346,7 @@ async function handleCapabilityProgress(args, logger, requestId) {
             sessionId: args.sessionId
         });
         // Get session directory first
-        const sessionDir = (0, session_utils_1.getAndValidateSessionDirectory)(args, false);
+        const sessionDir = (0, session_utils_1.getAndValidateSessionDirectory)(false);
         let sessionId = args.sessionId;
         let sessionFilePath;
         // If no sessionId provided, auto-discover the latest session

package/dist/core/generic-session-manager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Generic Session Manager
+ *
+ * Reusable file-based session management for MCP tools
+ * Provides CRUD operations with persistent storage
+ *
+ * Usage:
+ *   const manager = new GenericSessionManager<MySessionData>('myprefix', args);
+ *   const session = manager.createSession({ myData: 'value' });
+ */
+/**
+ * Generic session structure
+ * T is the type of data stored in the session
+ */
+export interface GenericSession<T = any> {
+    sessionId: string;
+    createdAt: string;
+    updatedAt: string;
+    data: T;
+}
+/**
+ * Generic session manager with file-based storage
+ */
+export declare class GenericSessionManager<T = any> {
+    private prefix;
+    private sessionDir;
+    private sessionsPath;
+    /**
+     * Create a new session manager
+     * @param prefix - Prefix for session IDs and directory (e.g., 'proj', 'pattern', 'test')
+     */
+    constructor(prefix: string);
+    /**
+     * Create a new session
+     * Pattern: {prefix}-{timestamp}-{uuid}
+     */
+    createSession(initialData?: T): GenericSession<T>;
+    /**
+     * Get an existing session
+     */
+    getSession(sessionId: string): GenericSession<T> | null;
+    /**
+     * Update session data (merges with existing data)
+     */
+    updateSession(sessionId: string, newData: Partial<T>): GenericSession<T> | null;
+    /**
+     * Replace session data entirely
+     */
+    replaceSession(sessionId: string, newData: T): GenericSession<T> | null;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): boolean;
+    /**
+     * List all sessions (returns session IDs)
+     */
+    listSessions(): string[];
+    /**
+     * Clear all sessions (useful for testing)
+     */
+    clearAllSessions(): void;
+    /**
+     * Save session to file
+     */
+    private saveSession;
+}
+//# sourceMappingURL=generic-session-manager.d.ts.map

package/dist/core/generic-session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-session-manager.d.ts","sourceRoot":"","sources":["../../src/core/generic-session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,qBAAa,qBAAqB,CAAC,CAAC,GAAG,GAAG;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAS;IAE7B;;;OAGG;gBACS,MAAM,EAAE,MAAM;IAW1B;;;OAGG;IACH,aAAa,CAAC,WAAW,GAAE,CAAW,GAAG,cAAc,CAAC,CAAC,CAAC;IAgB1D;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBvD;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAc/E;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAcvE;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAgBzC;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAgBxB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAiBxB;;OAEG;IACH,OAAO,CAAC,WAAW;CAIpB"}

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

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Generic Session Manager
+ *
+ * Reusable file-based session management for MCP tools
+ * Provides CRUD operations with persistent storage
+ *
+ * Usage:
+ *   const manager = new GenericSessionManager<MySessionData>('myprefix', args);
+ *   const session = manager.createSession({ myData: 'value' });
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericSessionManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const session_utils_1 = require("./session-utils");
+/**
+ * Generic session manager with file-based storage
+ */
+class GenericSessionManager {
+    prefix;
+    sessionDir;
+    sessionsPath;
+    /**
+     * Create a new session manager
+     * @param prefix - Prefix for session IDs and directory (e.g., 'proj', 'pattern', 'test')
+     */
+    constructor(prefix) {
+        this.prefix = prefix;
+        this.sessionDir = (0, session_utils_1.getAndValidateSessionDirectory)(true);
+        this.sessionsPath = path.join(this.sessionDir, `${prefix}-sessions`);
+        // Create sessions directory if it doesn't exist
+        if (!fs.existsSync(this.sessionsPath)) {
+            fs.mkdirSync(this.sessionsPath, { recursive: true });
+        }
+    }
+    /**
+     * Create a new session
+     * Pattern: {prefix}-{timestamp}-{uuid}
+     */
+    createSession(initialData = {}) {
+        const sessionId = `${this.prefix}-${Date.now()}-${(0, crypto_1.randomUUID)().substring(0, 8)}`;
+        const now = new Date().toISOString();
+        const session = {
+            sessionId,
+            createdAt: now,
+            updatedAt: now,
+            data: initialData,
+        };
+        this.saveSession(session);
+        return session;
+    }
+    /**
+     * Get an existing session
+     */
+    getSession(sessionId) {
+        try {
+            const sessionFile = path.join(this.sessionsPath, `${sessionId}.json`);
+            if (!fs.existsSync(sessionFile)) {
+                return null;
+            }
+            const sessionData = fs.readFileSync(sessionFile, 'utf8');
+            return JSON.parse(sessionData);
+        }
+        catch (error) {
+            console.error(`Failed to load session ${sessionId}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Update session data (merges with existing data)
+     */
+    updateSession(sessionId, newData) {
+        const session = this.getSession(sessionId);
+        if (!session) {
+            return null;
+        }
+        session.data = { ...session.data, ...newData };
+        session.updatedAt = new Date().toISOString();
+        this.saveSession(session);
+        return session;
+    }
+    /**
+     * Replace session data entirely
+     */
+    replaceSession(sessionId, newData) {
+        const session = this.getSession(sessionId);
+        if (!session) {
+            return null;
+        }
+        session.data = newData;
+        session.updatedAt = new Date().toISOString();
+        this.saveSession(session);
+        return session;
+    }
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId) {
+        try {
+            const sessionFile = path.join(this.sessionsPath, `${sessionId}.json`);
+            if (!fs.existsSync(sessionFile)) {
+                return false;
+            }
+            fs.unlinkSync(sessionFile);
+            return true;
+        }
+        catch (error) {
+            console.error(`Failed to delete session ${sessionId}:`, error);
+            return false;
+        }
+    }
+    /**
+     * List all sessions (returns session IDs)
+     */
+    listSessions() {
+        try {
+            if (!fs.existsSync(this.sessionsPath)) {
+                return [];
+            }
+            return fs
+                .readdirSync(this.sessionsPath)
+                .filter((file) => file.endsWith('.json'))
+                .map((file) => file.replace('.json', ''));
+        }
+        catch (error) {
+            console.error('Failed to list sessions:', error);
+            return [];
+        }
+    }
+    /**
+     * Clear all sessions (useful for testing)
+     */
+    clearAllSessions() {
+        try {
+            if (!fs.existsSync(this.sessionsPath)) {
+                return;
+            }
+            const sessions = fs.readdirSync(this.sessionsPath);
+            for (const file of sessions) {
+                if (file.endsWith('.json')) {
+                    fs.unlinkSync(path.join(this.sessionsPath, file));
+                }
+            }
+        }
+        catch (error) {
+            console.error('Failed to clear sessions:', error);
+        }
+    }
+    /**
+     * Save session to file
+     */
+    saveSession(session) {
+        const sessionFile = path.join(this.sessionsPath, `${session.sessionId}.json`);
+        fs.writeFileSync(sessionFile, JSON.stringify(session, null, 2), 'utf8');
+    }
+}
+exports.GenericSessionManager = GenericSessionManager;

package/dist/core/pattern-operations.js

@@ -238,7 +238,7 @@ async function handlePatternOperation(operation, args, logger, requestId, valida
                     });
                     // Clean up session file after successful Vector DB storage
                     try {
-                        const sessionDir = (0, session_utils_1.getAndValidateSessionDirectory)(args, false);
+                        const sessionDir = (0, session_utils_1.getAndValidateSessionDirectory)(false);
                         const sessionFile = path.join(sessionDir, 'pattern-sessions', `${workflowStep.sessionId}.json`);
                         if (fs.existsSync(sessionFile)) {
                             fs.unlinkSync(sessionFile);