@adityaaria/spark 6.0.17 → 6.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adityaaria/spark",
-  "version": "6.0.17",
+  "version": "6.0.19",
   "description": "SPARK skills and runtime bootstrap for coding agents",
   "type": "module",
   "publishConfig": {

package/skills/audit/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: audit
+description: Use to audit code quality, architecture, and security against the project's documented anti-patterns and standards.
+---
+
+# Audit (Meta-Skill)
+
+## Overview
+
+Use this skill to orchestrate a rigorous code review or architecture audit. You must NOT evaluate the code based on generic AI preferences or external "best practices" unless they align with the project's established rules. Your sole source of truth for the audit is the local knowledge base.
+
+**Announce at start:** "spark detection 💥 Using audit meta-skill to enforce project standards"
+
+## Standard Operating Procedure (SOP)
+
+You MUST execute this checklist strictly in order. Do not skip steps.
+
+### Phase 1: Context Grounding
+- `[ ]` **Step 1:** Read the local knowledge base located in `.docs/` (generated by the `project-scanner` skill). Focus heavily on `STANDARDS.md`, API contracts, and the list of Legacy Traps / Anti-patterns.
+- `[ ]` **Step 2:** Identify the exact boundaries of the code to be audited (e.g., a specific Pull Request, a newly written module, or a suspected legacy file).
+
+### Phase 2: Tactical Delegation (Review)
+- `[ ]` **Step 3:** Invoke the `receiving-code-review` (or `requesting-code-review` depending on your role) skill to structure your feedback.
+- `[ ]` **Step 4:** Compare the target code strictly against the Legacy Traps found in Phase 1. Actively flag any re-introduction of:
+  - Business logic leaks.
+  - Raw SQL/ORM mixing or N+1 queries.
+  - Undocumented bypass comments (`@ts-ignore`, `// HACK`).
+
+### Phase 3: Reporting
+- `[ ]` **Step 5:** Output an Audit Report summarizing the violations. If the code is clean, explicitly state that it complies with the `.docs/` standards.

package/skills/bug-fix/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: bug-fix
+description: Use to fix a bug while adhering strictly to the project's established standards and debugging protocols.
+---
+
+# Bug Fix (Meta-Skill)
+
+## Overview
+
+Use this skill to orchestrate a safe, standard-compliant bug fix. You are not allowed to blindly modify code based on assumptions. You must first ground yourself in the project's context, trace the bug systematically, and execute the fix using disciplined test-driven practices.
+
+**Announce at start:** "spark detection 💥 Using bug-fix meta-skill to coordinate this investigation"
+
+## Standard Operating Procedure (SOP)
+
+You MUST execute this checklist strictly in order. Do not skip steps.
+
+### Phase 1: Context Grounding
+Before touching any code, you must understand the rules of this repository.
+- `[ ]` **Step 1:** Read the local knowledge base located in `.docs/` (generated by the `project-scanner` skill). Specifically, look for `PROJECT_SCAN.md`, `STANDARDS.md`, and `API_CONTRACT.md`.
+- `[ ]` **Step 2:** Identify any Legacy Traps or Anti-Patterns documented in `.docs/`. You must NOT re-introduce these patterns while fixing the bug.
+
+### Phase 2: Tactical Delegation (Investigation)
+Do not guess the root cause. Delegate the investigation.
+- `[ ]` **Step 3:** Invoke the `systematic-debugging` skill. Follow its rigorous condition-based waiting and root-cause tracing protocols to find exactly what is broken.
+- `[ ]` *(Optional)*: If the bug spans multiple independent services, invoke `dispatching-parallel-agents` to investigate them concurrently.
+
+### Phase 3: Execution
+Once the root cause is proven (not guessed), fix it safely.
+- `[ ]` **Step 4:** Invoke the `test-driven-development` skill. Write a failing test that reproduces the bug, then implement the minimal code required to make it pass. Ensure your fix aligns with the architecture rules read in Phase 1.

package/skills/enhancement/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: enhancement
+description: Use to build a new feature or enhancement by aligning strictly with the project's existing business flow and domain architecture.
+---
+
+# Enhancement (Meta-Skill)
+
+## Overview
+
+Use this skill to orchestrate the safe addition of new features. Do not inject your own architectural preferences. You must ground yourself in the project's reality, scope the feature thoughtfully, plan it out, and execute it using the project's established conventions.
+
+**Announce at start:** "spark detection 💥 Using enhancement meta-skill to coordinate feature development"
+
+## Standard Operating Procedure (SOP)
+
+You MUST execute this checklist strictly in order. Do not skip steps.
+
+### Phase 1: Context Grounding
+- `[ ]` **Step 1:** Read the local knowledge base located in `.docs/` (generated by the `project-scanner` skill). Focus heavily on `BUSINESS_FLOW.md` and `DOMAINS/`.
+- `[ ]` **Step 2:** Determine which existing Domain will own this new feature, or if a completely new Domain is justified. Ensure your design respects the existing boundaries.
+
+### Phase 2: Tactical Delegation (Scoping & Planning)
+- `[ ]` **Step 3:** Invoke the `brainstorming` skill to map out edge cases, UX flows, and failure modes for this enhancement.
+- `[ ]` **Step 4:** Invoke the `writing-plans` skill to create a step-by-step implementation plan (saving to `docs/spark/plans/`). The plan MUST adhere to the standards found in Phase 1.
+
+### Phase 3: Execution
+- `[ ]` **Step 5:** Invoke the `executing-plans` skill to write the code.
+- `[ ]` *(Optional)*: If the enhancement is massive (e.g., touching frontend UI, backend API, and database migrations simultaneously), invoke `dispatching-parallel-agents` to delegate the sub-tasks to specialized subagents.

package/skills/project-scanner/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: project-scanner
+description: Use when analyzing an undocumented, legacy, or new project repository to extract its architectural and operational DNA.
+---
+
+# Project Scanner
+
+## Overview
+
+Use this skill to scan and document a codebase's architecture, operational rules, and hidden legacy traps. You must rely on file reading and listing tools rather than making assumptions. Traverse the root directory and key source directories to extract the project's DNA. This skill is polyglot—it applies to any tech stack (e.g., TypeScript, Go, Python, Java, PHP, Rust).
+
+**Announce at start:** "spark detection 💥 Using project-scanner to analyze repository DNA"
+
+**Save findings to:** The `.docs/` directory. Create it if it does not exist. For large projects, break down the documentation logically (e.g., `.docs/PROJECT_SCAN.md`, `.docs/API_CONTRACT.md`, `.docs/DOMAINS/`) instead of creating one massive monolithic file.
+
+## Handling Massive Codebases (Subagent Delegation)
+If the repository is extremely large and analyzing all four pillars sequentially risks exceeding context limits or taking too long:
+- Invoke the `dispatching-parallel-agents` skill.
+- Delegate specific analytical tasks to specialized subagents in parallel (e.g., Subagent A extracts the API Contract, Subagent B extracts the Business Flow).
+- Compile their findings into the final `.docs/` reports.
+
+## Target Extraction Artifacts
+
+Your final analysis must thoroughly document these four pillars:
+
+### 1. API CONTRACT
+Identify how the application communicates internally and externally.
+- **Priority Target:** Actively search for Swagger (`swagger.yaml`, `swagger.json`) or OpenAPI specifications. These are the single source of truth for the API contract.
+- **Secondary Targets:** Discover REST/GraphQL endpoints, gRPC protos, ORM schemas, Data Transfer Objects (DTOs), and core data models.
+- **Legacy Traps:** Flag any endpoints that violate current conventions or bypass standard authentication/validation layers.
+
+### 2. WORKFLOW
+Identify how the project is built, run, tested, and deployed.
+- **Targets:** CI/CD pipelines (e.g., `.github/workflows`, `.gitlab-ci.yml`), build scripts (Makefiles, Gradle, NPM scripts), Dockerfiles, and deployment scripts.
+- **Testing:** Identify the test framework, strategy (Unit, Integration, E2E), and explicitly highlight critical areas that lack test coverage.
+
+### 3. BUSINESS FLOW & DOMAINS
+Identify the core business logic and user journeys.
+- **Targets:** Core domains, domain services, use cases, and state machines.
+- **Domain Mapping:** Draft a list of business domains (e.g., Auth, Checkout, Inventory). Note their complexity, risk level, and the specific modules/packages that own them. Avoid forcing a domain split if the project is small.
+
+### 4. STANDARDS & ANTI-PATTERNS
+Identify conventions, rules, and technical debt enforced or found in the codebase.
+- **Targets:** Code styling conventions, linting rules, architectural patterns (e.g., MVC, Hexagonal, Clean Architecture).
+- **Anti-Pattern Detection (CRITICAL):** Actively search for and document legacy traps:
+  - Business logic leaked into controllers, presentation, or routing layers.
+  - Inconsistent database queries (e.g., raw queries mixed with ORM) or N+1 query problems.
+  - Misleading naming (e.g., `Utils` files containing heavy domain logic).
+  - Hardcoded external URLs, API keys, or magic numbers.
+  - Bypass comments (e.g., `@ts-ignore`, `// HACK`, `// FIXME`, `#nosec`) without explanations.
+  - Duplicated logic across modules.
+
+## Execution Checklist
+
+- `[ ]` **Step 1:** Announce skill usage exactly as required.
+- `[ ]` **Step 2:** Scan root configuration files and prioritize searching for Swagger/OpenAPI specifications.
+- `[ ]` **Step 3:** Scan source directory structures to infer the language, framework, and architectural patterns.
+- `[ ]` **Step 4:** Analyze testing frameworks, CI/CD workflows, and actively hunt for anti-patterns and legacy traps.
+- `[ ]` **Step 5:** Write the comprehensive report(s) into the `.docs/` directory.

package/src/cli/index.js

@@ -14,6 +14,12 @@ export async function run(argv = [], env = process.env) {
     return;
   }
 
+  if (command === 'dashboard' || command === 'ui') {
+    const { startDashboard } = await import('../dashboard/server.js');
+    startDashboard();
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }
 

package/src/dashboard/public/index.html

@@ -0,0 +1,369 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>SPARK | Command Center</title>
+    <!-- Google Fonts -->
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&display=swap" rel="stylesheet">
+    <!-- Marked.js for Markdown parsing -->
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <!-- Mermaid.js for Diagrams -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <style>
+        :root {
+            --bg-color: #0b0f19;
+            --glass-bg: rgba(255, 255, 255, 0.03);
+            --glass-border: rgba(255, 255, 255, 0.08);
+            --accent-glow: rgba(0, 255, 170, 0.15);
+            --accent: #00ffaa;
+            --danger: #ff4757;
+            --text-main: #f1f5f9;
+            --text-muted: #94a3b8;
+        }
+
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+
+        body {
+            font-family: 'Inter', sans-serif;
+            background-color: var(--bg-color);
+            color: var(--text-main);
+            min-height: 100vh;
+            display: flex;
+            background-image: 
+                radial-gradient(circle at 15% 50%, var(--accent-glow), transparent 25%),
+                radial-gradient(circle at 85% 30%, rgba(255, 71, 87, 0.1), transparent 25%);
+        }
+
+        /* Sidebar */
+        .sidebar {
+            width: 280px;
+            background: var(--glass-bg);
+            border-right: 1px solid var(--glass-border);
+            backdrop-filter: blur(12px);
+            padding: 24px;
+            display: flex;
+            flex-direction: column;
+        }
+
+        .logo {
+            font-size: 24px;
+            font-weight: 700;
+            letter-spacing: 2px;
+            margin-bottom: 40px;
+            display: flex;
+            align-items: center;
+            gap: 10px;
+        }
+
+        .logo span {
+            color: var(--accent);
+        }
+
+        .nav-item {
+            padding: 12px 16px;
+            margin-bottom: 8px;
+            border-radius: 8px;
+            cursor: pointer;
+            transition: all 0.2s ease;
+            color: var(--text-muted);
+            font-weight: 600;
+        }
+
+        .nav-item:hover {
+            background: rgba(255,255,255,0.05);
+            color: var(--text-main);
+        }
+
+        .nav-item.active {
+            background: rgba(0, 255, 170, 0.1);
+            color: var(--accent);
+            border: 1px solid rgba(0, 255, 170, 0.2);
+        }
+
+        /* Main Content */
+        .content {
+            flex: 1;
+            padding: 40px;
+            overflow-y: auto;
+            height: 100vh;
+        }
+
+        .header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 40px;
+        }
+
+        .header h1 {
+            font-size: 32px;
+            font-weight: 700;
+        }
+
+        .status-badge {
+            background: rgba(0, 255, 170, 0.1);
+            color: var(--accent);
+            padding: 6px 12px;
+            border-radius: 20px;
+            font-size: 14px;
+            font-weight: 600;
+            border: 1px solid rgba(0, 255, 170, 0.2);
+            display: flex;
+            align-items: center;
+            gap: 6px;
+        }
+
+        .status-badge::before {
+            content: '';
+            display: block;
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            background: var(--accent);
+            box-shadow: 0 0 8px var(--accent);
+        }
+
+        /* Cards / Panels */
+        .panel {
+            background: var(--glass-bg);
+            border: 1px solid var(--glass-border);
+            border-radius: 16px;
+            padding: 30px;
+            backdrop-filter: blur(10px);
+            margin-bottom: 30px;
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
+            animation: fadeIn 0.4s ease forwards;
+        }
+
+        @keyframes fadeIn {
+            from { opacity: 0; transform: translateY(10px); }
+            to { opacity: 1; transform: translateY(0); }
+        }
+
+        /* Markdown Styling */
+        .markdown-body {
+            line-height: 1.6;
+        }
+        .markdown-body h1, .markdown-body h2, .markdown-body h3 {
+            margin-top: 24px;
+            margin-bottom: 16px;
+            font-weight: 600;
+            color: var(--text-main);
+        }
+        .markdown-body h1 { font-size: 28px; border-bottom: 1px solid var(--glass-border); padding-bottom: 8px; }
+        .markdown-body h2 { font-size: 22px; }
+        .markdown-body p { margin-bottom: 16px; color: var(--text-muted); }
+        .markdown-body ul, .markdown-body ol { margin-bottom: 16px; padding-left: 24px; color: var(--text-muted); }
+        .markdown-body li { margin-bottom: 8px; }
+        .markdown-body code {
+            background: rgba(0,0,0,0.3);
+            padding: 3px 6px;
+            border-radius: 4px;
+            font-family: monospace;
+            font-size: 14px;
+            color: #ff9e64;
+        }
+        .markdown-body pre {
+            background: #111520;
+            padding: 16px;
+            border-radius: 8px;
+            overflow-x: auto;
+            border: 1px solid var(--glass-border);
+            margin-bottom: 16px;
+        }
+        .markdown-body pre code {
+            background: none;
+            padding: 0;
+            color: #f1f5f9;
+        }
+
+        /* Empty State */
+        .empty-state {
+            text-align: center;
+            padding: 60px 20px;
+            color: var(--text-muted);
+        }
+        .empty-state h3 { margin-bottom: 10px; color: var(--text-main); }
+        .empty-state p { margin-bottom: 20px; }
+        .btn {
+            background: var(--text-main);
+            color: var(--bg-color);
+            border: none;
+            padding: 10px 24px;
+            border-radius: 6px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: transform 0.1s ease;
+        }
+        .btn:hover { transform: scale(1.05); }
+
+    </style>
+</head>
+<body>
+
+    <div class="sidebar">
+        <div class="logo">
+            <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="var(--accent)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/>
+            </svg>
+            SPARK<span>UI</span>
+        </div>
+        <div id="nav-container">
+            <!-- Nav items will be injected here -->
+        </div>
+    </div>
+
+    <div class="content">
+        <div class="header">
+            <h1 id="page-title">Dashboard Overview</h1>
+            <div class="status-badge" id="agent-status">Checking Agents...</div>
+        </div>
+
+        <div id="content-container">
+            <div class="panel empty-state">
+                <h3>Loading Knowledge Base...</h3>
+                <p>Fetching architectural DNA from .docs/</p>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        // Initialize Mermaid
+        mermaid.initialize({ 
+            startOnLoad: false, 
+            theme: 'dark',
+            fontFamily: 'Inter'
+        });
+
+        let docsData = [];
+
+        async function fetchDocs() {
+            try {
+                const res = await fetch('/api/docs');
+                const data = await res.json();
+                
+                if (data.error) {
+                    renderEmptyState(data.error);
+                    return;
+                }
+                
+                docsData = data.docs;
+                renderNav();
+                
+                // Show first doc by default or overview
+                if(docsData.length > 0) {
+                    // Try to find PROJECT_SCAN.md first
+                    const mainDoc = docsData.find(d => d.filename === 'PROJECT_SCAN.md') || docsData[0];
+                    renderDoc(mainDoc.filename);
+                } else {
+                    renderEmptyState("The .docs/ directory is empty. Generate artifacts using the project-scanner skill.");
+                }
+            } catch (err) {
+                renderEmptyState("Failed to connect to the SPARK local server.");
+            }
+        }
+
+        async function fetchStatus() {
+            try {
+                const res = await fetch('/api/status');
+                const data = await res.json();
+                const badge = document.getElementById('agent-status');
+                if (data.installed && data.agents) {
+                    badge.innerHTML = `Agents Active: ${data.agents.join(', ')}`;
+                } else {
+                    badge.innerHTML = `No Agents Detected`;
+                    badge.style.color = 'var(--text-muted)';
+                    badge.style.borderColor = 'var(--glass-border)';
+                }
+            } catch (e) {
+                console.error(e);
+            }
+        }
+
+        function renderNav() {
+            const nav = document.getElementById('nav-container');
+            nav.innerHTML = '';
+            
+            docsData.forEach(doc => {
+                const el = document.createElement('div');
+                el.className = 'nav-item';
+                el.innerText = doc.filename.replace('.md', '').replace(/_/g, ' ');
+                el.onclick = () => renderDoc(doc.filename);
+                nav.appendChild(el);
+            });
+        }
+
+        function renderDoc(filename) {
+            // Update active state
+            document.querySelectorAll('.nav-item').forEach(el => {
+                if (el.innerText === filename.replace('.md', '').replace(/_/g, ' ')) {
+                    el.classList.add('active');
+                } else {
+                    el.classList.remove('active');
+                }
+            });
+
+            const doc = docsData.find(d => d.filename === filename);
+            if (!doc) return;
+
+            document.getElementById('page-title').innerText = filename;
+            
+            // Render Markdown
+            const container = document.getElementById('content-container');
+            const parsedHTML = marked.parse(doc.content);
+            
+            container.innerHTML = `
+                <div class="panel markdown-body">
+                    ${parsedHTML}
+                </div>
+            `;
+
+            // Render Mermaid diagrams if any
+            const codeBlocks = container.querySelectorAll('code.language-mermaid');
+            codeBlocks.forEach((block, index) => {
+                const graphDefinition = block.innerText;
+                const parent = block.parentElement; // the <pre> tag
+                
+                // Create a div for mermaid to render into
+                const mermaidDiv = document.createElement('div');
+                mermaidDiv.className = 'mermaid-chart';
+                mermaidDiv.id = `mermaid-${index}`;
+                
+                // Render it
+                mermaid.render(`mermaid-graph-${index}`, graphDefinition).then((result) => {
+                    mermaidDiv.innerHTML = result.svg;
+                    parent.replaceWith(mermaidDiv);
+                }).catch(e => {
+                    console.error("Mermaid error:", e);
+                });
+            });
+        }
+
+        function renderEmptyState(message) {
+            document.getElementById('content-container').innerHTML = `
+                <div class="panel empty-state">
+                    <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="var(--text-muted)" stroke-width="1.5" style="margin-bottom: 20px;">
+                        <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path>
+                        <polyline points="14 2 14 8 20 8"></polyline>
+                        <line x1="16" y1="13" x2="8" y2="13"></line>
+                        <line x1="16" y1="17" x2="8" y2="17"></line>
+                        <polyline points="10 9 9 9 8 9"></polyline>
+                    </svg>
+                    <h3>No Data Available</h3>
+                    <p>${message}</p>
+                </div>
+            `;
+        }
+
+        // Init
+        fetchStatus();
+        fetchDocs();
+
+    </script>
+</body>
+</html>

package/src/dashboard/server.js

@@ -0,0 +1,86 @@
+import fs from 'fs';
+import path from 'path';
+import http from 'http';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PORT = 4321;
+const PUBLIC_DIR = path.join(__dirname, 'public');
+const DOCS_DIR = path.join(process.cwd(), '.docs');
+const LOCK_FILE = path.join(process.cwd(), '.spark-lock.json');
+
+const server = http.createServer((req, res) => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+
+  // API Route: Get all markdown docs
+  if (req.url === '/api/docs' && req.method === 'GET') {
+    res.setHeader('Content-Type', 'application/json');
+    if (!fs.existsSync(DOCS_DIR)) {
+      return res.end(JSON.stringify({ error: 'No .docs/ directory found in this project. Please run project-scanner skill first.' }));
+    }
+
+    try {
+      const files = fs.readdirSync(DOCS_DIR).filter(f => f.endsWith('.md'));
+      const docs = files.map(filename => {
+        const content = fs.readFileSync(path.join(DOCS_DIR, filename), 'utf-8');
+        return { filename, content };
+      });
+      return res.end(JSON.stringify({ docs }));
+    } catch (e) {
+      return res.end(JSON.stringify({ error: e.message }));
+    }
+  }
+
+  // API Route: Get Spark Lock status
+  if (req.url === '/api/status' && req.method === 'GET') {
+    res.setHeader('Content-Type', 'application/json');
+    let status = { installed: false, agents: [] };
+    if (fs.existsSync(LOCK_FILE)) {
+      try {
+        status = JSON.parse(fs.readFileSync(LOCK_FILE, 'utf-8'));
+        status.installed = true;
+      } catch (e) {}
+    }
+    return res.end(JSON.stringify(status));
+  }
+
+  // Static File Server
+  let filePath = req.url === '/' ? '/index.html' : req.url;
+  // Prevent path traversal
+  filePath = path.normalize(filePath).replace(/^(\.\.[\/\\])+/, '');
+  const ext = path.extname(filePath);
+  
+  const contentTypes = {
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'text/javascript',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml'
+  };
+
+  const contentType = contentTypes[ext] || 'text/plain';
+  const fullPath = path.join(PUBLIC_DIR, filePath);
+
+  if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+    res.writeHead(200, { 'Content-Type': contentType });
+    fs.createReadStream(fullPath).pipe(res);
+  } else {
+    res.writeHead(404);
+    res.end('404 Not Found');
+  }
+});
+
+export function startDashboard() {
+  server.listen(PORT, async () => {
+    console.log(`\n🚀 SPARK Dashboard running at http://localhost:${PORT}`);
+    console.log(`Open this URL in your browser to view the AI Knowledge Base.`);
+    console.log(`Press Ctrl+C to stop.\n`);
+    
+    // Attempt to open browser automatically
+    const { exec } = await import('child_process');
+    const startCmd = process.platform == 'darwin' ? 'open' : process.platform == 'win32' ? 'start' : 'xdg-open';
+    exec(`${startCmd} http://localhost:${PORT}`);
+  });
+}