@vfarcic/dot-ai 0.174.0 → 0.176.0

package/dist/tools/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,eAAO,MAAM,eAAe,UAAU,CAAC;AACvC,eAAO,MAAM,sBAAsB,iWAAuV,CAAC;AAG3X,eAAO,MAAM,uBAAuB;;;CAGnC,CAAC;AAGF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAGD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAgED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAiH7D"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,eAAO,MAAM,eAAe,UAAU,CAAC;AACvC,eAAO,MAAM,sBAAsB,iWAAuV,CAAC;AAG3X,eAAO,MAAM,uBAAuB;;;CAGnC,CAAC;AAGF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,KAAK,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,GAAG,CAAC;QACX,MAAM,EAAE,GAAG,CAAC;KACb,CAAC,CAAC;CACJ;AAGD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AA8ED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAsI7D"}

package/dist/tools/query.js

@@ -49,6 +49,7 @@ const ai_provider_factory_1 = require("../core/ai-provider-factory");
 const capability_tools_1 = require("../core/capability-tools");
 const resource_tools_1 = require("../core/resource-tools");
 const kubectl_tools_1 = require("../core/kubectl-tools");
+const generic_session_manager_1 = require("../core/generic-session-manager");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 // Tool metadata for MCP registration
@@ -59,6 +60,19 @@ exports.QUERY_TOOL_INPUT_SCHEMA = {
     intent: zod_1.z.string().min(1).max(1000).describe('Natural language query about the cluster'),
     interaction_id: zod_1.z.string().optional().describe('INTERNAL ONLY - Do not populate. Used for evaluation dataset generation.')
 };
+/**
+ * Get visualization URL if WEB_UI_BASE_URL is configured
+ * PRD #317: Feature toggle - only include URL when env var is set
+ */
+function getVisualizationUrl(sessionId) {
+    const baseUrl = process.env.WEB_UI_BASE_URL;
+    if (!baseUrl) {
+        return undefined;
+    }
+    // Remove trailing slash if present, then append /v/{sessionId}
+    const normalizedBaseUrl = baseUrl.replace(/\/$/, '');
+    return `${normalizedBaseUrl}/v/${sessionId}`;
+}
 /**
  * Parse the AI's final JSON response for summary only
  */
@@ -179,11 +193,29 @@ async function handleQueryTool(args) {
             iterations: result.iterations,
             toolsUsed
         });
+        // Store session for visualization (PRD #317)
+        const sessionManager = new generic_session_manager_1.GenericSessionManager('qry');
+        const session = sessionManager.createSession({
+            intent,
+            summary,
+            toolsUsed,
+            iterations: result.iterations,
+            toolCallsExecuted: result.toolCallsExecuted
+        });
+        // PRD #317: Include visualization URL when WEB_UI_BASE_URL is configured
+        const visualizationUrl = getVisualizationUrl(session.sessionId);
+        logger.info('Session created for visualization', {
+            requestId,
+            sessionId: session.sessionId,
+            ...(visualizationUrl && { visualizationUrl })
+        });
         const output = {
             success: true,
             summary,
             toolsUsed,
-            iterations: result.iterations
+            iterations: result.iterations,
+            sessionId: session.sessionId,
+            ...(visualizationUrl && { visualizationUrl })
         };
         return {
             content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vfarcic/dot-ai",
-  "version": "0.174.0",
+  "version": "0.176.0",
   "description": "AI-powered development productivity platform that enhances software development workflows through intelligent automation and AI-driven assistance",
   "mcpName": "io.github.vfarcic/dot-ai",
   "main": "dist/index.js",

package/prompts/visualize-query.md

@@ -0,0 +1,113 @@
+# Query Visualization Generator
+
+You are a Kubernetes cluster visualization expert. Analyze the query results and generate visualizations that reveal relationships and patterns in the data.
+
+## User Query
+
+{{{intent}}}
+
+## Query Results
+
+{{{toolCallsData}}}
+
+## Your Task
+
+Thoroughly analyze the query results and surface everything valuable you can find. This includes but is not limited to:
+- Relationships between resources
+- Resource status and health
+- Patterns and architectural insights
+- Anything else worth knowing about these resources
+
+If the provided data isn't sufficient for deep analysis, use the available tools to gather additional information. Don't limit yourself to what's already in the context - investigate further if it would produce more valuable insights.
+
+## Analysis Approach
+
+Include both obvious and non-obvious findings:
+
+### Level 1: Obvious Relationships (include these)
+- `metadata.ownerReferences` links
+- Label selectors matching labels
+- Explicit name references in spec fields
+
+### Level 2: Deep Analysis (this is where you add unique value)
+Go beyond the obvious. Analyze the data thoroughly. Here are some examples - but don't limit yourself to these:
+
+- Inferred dependencies from env vars, config names, port numbers, mount paths
+- Architectural patterns like sidecars, init containers, deployment strategies
+- Potential issues: missing limits, no health checks, security concerns, single points of failure
+- Implicit relationships from naming patterns, shared labels, operator conventions
+- Capacity and scaling considerations
+
+These are just examples. Analyze EVERYTHING in the data - annotations, labels, all spec fields, status conditions, anything. Surface whatever is valuable. The non-obvious insights are what make this worthwhile.
+
+Do NOT assume what resources exist. Analyze only what's in the data.
+
+## Output Format
+
+Respond with ONLY a JSON object (no markdown code fences, no extra text):
+
+{
+  "title": "Descriptive title based on what was found",
+  "visualizations": [...],
+  "insights": [...]
+}
+
+## Visualization Types
+
+Generate as many or as few visualizations as add value. You can:
+- Include multiple visualizations of the same type (e.g., several mermaid diagrams for different aspects)
+- Skip any type entirely if it doesn't add value for this data
+- Use whatever combination best represents what you found
+
+Each visualization:
+
+```
+{
+  "id": "unique-id",
+  "label": "Tab Label",
+  "type": "mermaid" | "table" | "cards" | "code",
+  "content": <type-specific-content>
+}
+```
+
+### mermaid
+For showing relationships between resources.
+- `content`: Valid Mermaid diagram string
+- Use `graph TD` or `graph LR` depending on relationship type
+- Use subgraphs to group by namespace or logical grouping
+- Arrows: `-->` for ownership/direct, `-.->` for inferred/indirect
+- Keep readable - summarize similar resources rather than showing every instance
+
+### table
+For listing resources with their properties.
+- `content`: `{ "headers": ["Col1", "Col2"], "rows": [["val1", "val2"]] }`
+- Choose columns relevant to the resource types present
+- Include status/condition information when available
+
+### cards
+For highlighting individual resources with status.
+- `content`: `[{ "id": "unique", "title": "Name", "description": "Status info", "tags": ["tag1"] }]`
+- Use for resources where individual status matters
+- Tags should reflect actual state from the data
+
+### code
+For showing raw data or configurations.
+- `content`: `{ "language": "yaml" | "json", "code": "..." }`
+- Use sparingly - only when raw output adds value
+
+## Insights
+
+Generate insights that add value beyond what someone could see by just reading the raw data. Prioritize non-obvious findings over summaries of what's there.
+
+Each insight should:
+- Reference specific resource names from the data
+- Explain WHY it matters, not just WHAT you found
+- Be actionable when highlighting issues
+
+## Rules
+
+1. **Data-driven only** - Generate visualizations based on actual resources present
+2. **Skip empty visualizations** - Don't include a topology diagram if there are no relationships
+3. **Valid output** - Ensure Mermaid syntax is correct and JSON is valid
+4. **Resource-agnostic** - Handle any Kubernetes resource type (core, CRDs, operators)
+5. **JSON only** - No markdown fences, no explanations outside the JSON structure

package/shared-prompts/prd-create.md

@@ -164,9 +164,7 @@ If user chooses option 1, first commit and push the PRD (same as Option 2), then
 
 **PRD committed and pushed.**
 
-To start working on this PRD, run the `prd-start` prompt with the PRD ID: `prd-start [issue-id]`
-
-*Note: Different agents/clients may have different syntax for executing commands and prompts (e.g., `/prd-start [issue-id]` in Claude Code, or other syntax in different MCP clients). Start a new conversation/context to run the prompt.*
+To start working on this PRD, run `/prd-start [issue-id]`
 
 ---
 

package/shared-prompts/prd-next.md

@@ -28,7 +28,7 @@ You are helping analyze an existing Product Requirements Document (PRD) to sugge
 **Skip detection/analysis if recent conversation shows:**
 - **Recent PRD work discussed** - "We just worked on PRD 29", "Just completed PRD update", etc.
 - **Specific PRD mentioned** - "PRD #X", "MCP Prompts PRD", etc.
-- **PRD-specific commands used** - Recent use of `prd-update-progress`, `prd-start` with specific PRD
+- **PRD-specific commands used** - Recent use of `/prd-update-progress`, `/prd-start` with specific PRD
 - **Clear work context** - Discussion of specific features, tasks, or requirements for a known PRD
 
 **If context is clear:**
@@ -248,16 +248,16 @@ This command should:
 
 ## Step 8: Update Progress After Completion
 
-After the user completes the task implementation, prompt them to update PRD progress:
+**CRITICAL: Do NOT update the PRD yourself. Do NOT edit PRD files directly. Your job is to prompt the user to run the update command.**
+
+After the user completes the task implementation, output ONLY this message:
 
 ---
 
 **Task implementation complete.**
 
-To update PRD progress and commit your work, run the `prd-update-progress` prompt.
-
-*Note: Different agents/clients may have different syntax for executing commands and prompts (e.g., `/prd-update-progress` in Claude Code, or other syntax in different MCP clients).*
+To update PRD progress and commit your work, run `/prd-update-progress`.
 
 ---
 
-This ensures a smooth workflow from task selection → implementation → progress tracking → next task.
+Then STOP. Do not proceed further. The `/prd-update-progress` command handles PRD updates, progress tracking, and commits. This separation ensures proper workflow and avoids duplicate/conflicting updates.

package/shared-prompts/prd-start.md

@@ -2,41 +2,52 @@
 name: prd-start
 description: Start working on a PRD implementation
 category: project-management
+arguments:
+  - name: prdNumber
+    description: PRD number to start working on (e.g., 306)
+    required: false
 ---
 
 # PRD Start - Begin Implementation Work
 
 ## Instructions
 
-You are helping initiate active implementation work on a specific Product Requirements Document (PRD). This command bridges the gap between PRD planning and actual development work by setting up the implementation context and providing clear next steps.
+You are helping initiate active implementation work on a specific Product Requirements Document (PRD). This command sets up the implementation context (validates readiness, creates branch, prepares environment) then hands off to `/prd-next` for task identification.
 
-**IMPORTANT**: Do NOT include time estimates or effort estimates in your responses. Focus on task prioritization, dependencies, and clear next steps without speculating on duration.
+**IMPORTANT**: Do NOT include time estimates or effort estimates in your responses. Focus on setup and readiness without speculating on duration.
 
 ## Process Overview
 
-1. **Select Target PRD** - Ask user which PRD they want to implement
-2. **Validate PRD Readiness** - Ensure the selected PRD is ready for implementation
-3. **Set Up Implementation Context** - Prepare the development environment
-4. **Identify Starting Point** - Determine the best first implementation task
-5. **Begin Implementation** - Launch into actual development work
+1. **Select Target PRD** - Identify which PRD to implement
+2. **Validate PRD Readiness** - Ensure the PRD is ready for implementation
+3. **Set Up Implementation Context** - Create branch and prepare environment
+4. **Hand Off to prd-next** - Delegate task identification to the appropriate prompt
 
-## Step 0: Context Awareness Check
+## Step 0: Check for PRD Argument
 
-**FIRST: Check if PRD context is already clear from recent conversation:**
+**If `prdNumber` argument is provided ({{prdNumber}}):**
+- Skip context check and auto-detection
+- Use PRD #{{prdNumber}} directly
+- Proceed to Step 2 (PRD Readiness Validation)
 
-**Skip detection/analysis if recent conversation shows:**
+**If `prdNumber` argument is NOT provided:**
+- Continue to context awareness check below
+
+## Step 0b: Context Awareness Check
+
+**Check if PRD context is already clear from recent conversation:**
+
+**Skip detection if recent conversation shows:**
 - **Recent PRD work discussed** - "We just worked on PRD 29", "Just completed PRD update", etc.
 - **Specific PRD mentioned** - "PRD #X", "MCP Prompts PRD", etc.
-- **PRD-specific commands used** - Recent use of `prd-update-progress`, `prd-start` with specific PRD
+- **PRD-specific commands used** - Recent use of `/prd-update-progress`, `/prd-start` with specific PRD
 - **Clear work context** - Discussion of specific features, tasks, or requirements for a known PRD
 
 **If context is clear:**
-- Skip to Step 2 (PRD Readiness Validation) using the known PRD 
-- Use conversation history to understand current state and recent progress
-- Proceed directly with readiness validation based on known PRD status
+- Skip to Step 2 (PRD Readiness Validation) using the known PRD
 
 **If context is unclear:**
-- Continue to Step 1 (PRD Detection) for full analysis
+- Continue to Step 1 (PRD Detection)
 
 ## Step 1: Smart PRD Detection (Only if Context Unclear)
 
@@ -55,35 +66,16 @@ You are helping initiate active implementation work on a specific Product Requir
    - Modified `prds/12-*.md` → PRD 12
    - Changes in feature-specific directories
 
-4. **Available PRDs Discovery** - List all PRDs in `prds/` directory:
-   - `prds/12-documentation-testing.md`
-   - `prds/13-cicd-documentation-testing.md`
+4. **Available PRDs Discovery** - List all PRDs in `prds/` directory
 
 5. **Fallback to User Choice** - Only if context detection fails, ask user to specify
 
-**PRD Detection Implementation:**
-```bash
-# Use these tools to gather context:
-# 1. Check git branch: gitStatus shows current branch
-# 2. Check git status: Look for modified PRD files  
-# 3. List PRDs: Use LS or Glob to find prds/*.md files
-# 4. Recent commits: Use Bash 'git log --oneline -n 5' for recent context
-```
-
 **Detection Logic:**
 - **High Confidence**: Branch name matches PRD pattern (e.g., `feature/prd-12-documentation-testing`)
 - **Medium Confidence**: Modified PRD files in git status or recent commits mention PRD
 - **Low Confidence**: Multiple PRDs available, use heuristics (most recent, largest)
 - **No Context**: Present available options to user
 
-**Example Detection Outputs:**
-```markdown
-🎯 **Auto-detected PRD 12** (Documentation Testing)
-- Branch: `feature/prd-12-documentation-testing` ✅
-- Modified files: `prds/12-documentation-testing.md` ✅
-- Recent commits mention PRD 12 features ✅
-```
-
 **If context detection fails, ask the user:**
 
 ```markdown
@@ -91,7 +83,7 @@ You are helping initiate active implementation work on a specific Product Requir
 
 Please provide the PRD number (e.g., "12", "PRD 12", or "36").
 
-**Not sure which PRD to work on?** 
+**Not sure which PRD to work on?**
 Execute `dot-ai:prds-get` prompt to see all available PRDs organized by priority and readiness.
 
 **Your choice**: [Wait for user input]
@@ -99,8 +91,6 @@ Execute `dot-ai:prds-get` prompt to see all available PRDs organized by priority
 
 **Once PRD is identified:**
 - Read the PRD file from `prds/[issue-id]-[feature-name].md`
-- Analyze completion status across all sections
-- Identify patterns in completed vs remaining work
 
 ## Step 2: PRD Readiness Validation
 
@@ -122,14 +112,16 @@ For documentation-first PRDs:
 ### Implementation Readiness Checklist
 ```markdown
 ## PRD Readiness Check
-- [ ] All functional requirements defined ✅
-- [ ] Success criteria measurable ✅  
-- [ ] Dependencies available ✅
-- [ ] Documentation complete ✅
-- [ ] Integration points clear ✅
-- [ ] Implementation approach decided ✅
+- [ ] All functional requirements defined
+- [ ] Success criteria measurable
+- [ ] Dependencies available
+- [ ] Documentation complete
+- [ ] Integration points clear
+- [ ] Implementation approach decided
 ```
 
+**If PRD is not ready:** Inform the user what's missing and suggest they complete PRD planning first.
+
 ## Step 3: Implementation Context Setup
 
 **⚠️ MANDATORY: Complete this step BEFORE proceeding to Step 4**
@@ -160,76 +152,29 @@ For documentation-first PRDs:
 
 **DO NOT proceed to Step 4 until branch setup is confirmed.**
 
-## Step 4: Identify Implementation Starting Point
-
-### Critical Path Analysis
-Identify the highest-priority first task by analyzing:
-- **Foundation requirements**: Core capabilities that other features depend on
-- **Blocking dependencies**: Items that prevent other work from starting
-- **Quick wins**: Early deliverables that provide validation or value
-- **Risk mitigation**: High-uncertainty items that should be tackled early
-
-### Implementation Phases
-For complex PRDs, identify logical implementation phases:
-1. **Phase 1 - Foundation**: Core data structures, interfaces, basic functionality
-2. **Phase 2 - Integration**: Connect with existing systems, implement workflows
-3. **Phase 3 - Enhancement**: Advanced features, optimization, polish
-4. **Phase 4 - Validation**: Testing, documentation updates, deployment
+## Step 4: Hand Off to prd-next
 
-### First Task Recommendation
-Select the single best first task based on:
-- **Dependency analysis**: No blocking dependencies
-- **Value delivery**: Provides meaningful progress toward PRD goals
-- **Learning opportunity**: Generates insights for subsequent work
-- **Validation potential**: Allows early testing of key assumptions
-
-## Step 5: Begin Implementation
-
-### Implementation Kickoff
-Present the implementation plan:
+Once the implementation context is set up, present this message to the user:
 
 ```markdown
-# 🚀 Starting Implementation: [PRD Name]
-
-## Selected First Task: [Task Name]
+## Ready for Implementation 🚀
 
-**Why this task first**: [Clear rationale for why this is the optimal starting point]
-
-**What you'll build**: [Concrete description of what will be implemented]
-
-**Success criteria**: [How you'll know this task is complete]
-
-**Next steps after this**: [What becomes possible once this is done]
-
-## Implementation Approach
-[Brief technical approach and key decisions]
-
-## Ready to Start?
-Type 'yes' to begin implementation, or let me know if you'd prefer to start with a different task.
-```
-
-### Implementation Launch
-If confirmed, provide:
-- **Detailed task breakdown**: Step-by-step implementation guide
-- **Code structure recommendations**: Files to create/modify
-- **Testing approach**: How to validate the implementation
-- **Progress checkpoints**: When to update the PRD with progress
-
-## Step 6: Update Progress After Completion
-
-After the user completes the task implementation, prompt them to update PRD progress:
+**PRD**: [PRD Name] (#[PRD Number])
+**Branch**: `[branch-name]`
+**Status**: Ready for development
 
 ---
 
-**Task implementation complete.**
-
-To update PRD progress and commit your work, run the `prd-update-progress` prompt.
-
-*Note: Different agents/clients may have different syntax for executing commands and prompts (e.g., `/prd-update-progress` in Claude Code, or other syntax in different MCP clients).*
+To identify and start working on your first task, run `/prd-next`.
+```
 
----
+**⚠️ STOP HERE - DO NOT:**
+- Identify or recommend tasks to work on
+- Analyze implementation priorities or critical paths
+- Start any implementation work
+- Continue beyond presenting the handoff message
 
-This ensures a smooth workflow from task selection → implementation → progress tracking → next task.
+`/prd-next` handles all task identification and implementation guidance.
 
 ## Success Criteria
 
@@ -237,13 +182,10 @@ This command should:
 - ✅ Successfully identify the target PRD for implementation
 - ✅ Validate that the PRD is ready for development work
 - ✅ Set up proper implementation context (branch, environment)
-- ✅ Identify the optimal first implementation task
-- ✅ Provide clear, actionable next steps for beginning development
-- ✅ Bridge the gap between planning and actual coding work
+- ✅ Hand off to `/prd-next` for task identification
+- ✅ Bridge the gap between PRD planning and development setup
 
 ## Notes
 
-- This command is designed for PRDs that are ready to move from planning to implementation
-- Use `prd-next` for ongoing implementation guidance on what to work on next
-- Use `prd-update-progress` to track implementation progress against PRD requirements
-- Use `prd-done` when PRD implementation is complete and ready for deployment/closure
+- This command focuses on **setup only** - it validates readiness, creates the branch, and prepares the environment
+- Once setup is complete, `/prd-next` handles all task identification, implementation guidance, and progress tracking

package/shared-prompts/prd-update-progress.md

@@ -302,7 +302,7 @@ After completing the PRD update and committing changes, guide the user based on
 
 To continue working on this PRD:
 1. Clear/reset the conversation context
-2. Run the `prd-next` prompt to get the next task
+2. Run `/prd-next` to get the next task
 
 ---
 
@@ -314,8 +314,6 @@ To continue working on this PRD:
 
 To finalize:
 1. Clear/reset the conversation context
-2. Run the `prd-done` prompt to move the PRD to the done folder and close the GitHub issue
+2. Run `/prd-done` to move the PRD to the done folder and close the GitHub issue
 
 ---
-
-*Note: Different agents/clients may have different syntax for executing prompts (e.g., `/prd-next`, `/prd-done` in Claude Code, or other syntax in different MCP clients).*