@adityaaria/spark 6.0.20 → 6.0.22

package/bin/spark-install.sh

@@ -99,8 +99,8 @@ print_help() {
     bash bin/spark-install.sh [options]
 
   Options:
-    -g, --global    Install to global agent config (~/.agent/skills/)
-                    Default: project scope (./.agent/skills/)
+    -g, --global    Install to global agent config (~/.agents/skills/)
+                    Default: project scope (./.agents/skills/)
     --force         Re-install even if already installed
     --dry-run       Show what would be done without making changes
     -u, --uninstall Safely remove SPARK from agent configs

package/package.json

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

package/skills/project-scanner/SKILL.md

@@ -11,7 +11,12 @@ Use this skill to scan and document a codebase's architecture, operational rules
 
 **Announce at start:** "spark detection 💥 Using project-scanner to analyze repository DNA"
 
-**Save findings to:** The `.docs/` directory. **You must physically create this directory and save the files to disk using your tools. Do NOT just print the output to the user.** 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.
+**Save findings to:** The `.docs/` directory. **You must physically create this directory and save the files to disk using your tools. Do NOT just print the output to the user.** 
+
+## Multi-Project Workspaces (CRITICAL)
+If the workspace contains multiple independent projects or repositories (e.g., a `frontend` folder and a `backend` folder), you MUST generate a separate `.docs/` directory inside EACH project's root folder (e.g., `frontend/.docs/`, `backend/.docs/`). Do NOT combine them into a single global `.docs/` or dump everything into just one project's folder. Treat each independent project as its own ecosystem that requires its own documentation.
+
+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:
@@ -53,7 +58,8 @@ Identify conventions, rules, and technical debt enforced or found in the codebas
 ## 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 (CRITICAL):** You MUST use your file-writing tools to physically create the `.docs/` directory and save the markdown files (e.g. `PROJECT_SCAN.md`, `API_CONTRACT.md`) into it. DO NOT just print the summary into the chat! You must physically write the files to disk.
+- `[ ]` **Step 2:** Identify if the workspace contains multiple independent projects (e.g., frontend vs backend). If so, plan to scan and generate `.docs/` for EACH project separately.
+- `[ ]` **Step 3:** Scan root configuration files and prioritize searching for Swagger/OpenAPI specifications.
+- `[ ]` **Step 4:** Scan source directory structures to infer the language, framework, and architectural patterns.
+- `[ ]` **Step 5:** Analyze testing frameworks, CI/CD workflows, and actively hunt for anti-patterns and legacy traps.
+- `[ ]` **Step 6 (CRITICAL):** You MUST use your file-writing tools to physically create the `.docs/` directory (inside each project root if multi-repo) and save the markdown files (e.g. `PROJECT_SCAN.md`, `API_CONTRACT.md`) into it. DO NOT just print the summary into the chat! You must physically write the files to disk.

package/skills/using-spark/SKILL.md

@@ -10,7 +10,12 @@ If you were dispatched as a subagent to execute a specific task, skip this skill
 <EXTREMELY-IMPORTANT>
 If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
 
-IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+IF A SKILL APPLIES TO YOUR TASK, OR IF THE USER EXPLICITLY REQUESTS A SKILL, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT IMMEDIATELY.
+
+**Do NOT ask clarifying questions first.**
+**Do NOT start a conversation.**
+**Do NOT explain what you are going to do.**
+**JUST EXECUTE THE SKILL DIRECTLY AS YOUR FIRST TOOL CALL.**
 
 This is not negotiable. This is not optional. You cannot rationalize your way out of this.
 </EXTREMELY-IMPORTANT>
@@ -49,6 +54,8 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file")
 
 **Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
 
+**CRITICAL:** If the user mentions a specific skill by name (e.g., "scan project", "project-scanner", "run deployment"), you MUST invoke that skill IMMEDIATELY as your very first tool call. Do not answer conversationally. Do not ask for confirmation. Execute the skill first.
+
 ## Announcement Format
 When you invoke a skill, you MUST announce it to the developer using exactly this format as the very first thing you say:
 `spark detection 💥 Using [skill] to [purpose]`

package/src/cli/output.js

@@ -24,7 +24,7 @@ export function printHelp() {
   printLine('');
   printMuted('Wraps the native SPARK installer (bin/spark-install.sh).');
   printLine('');
-  printLine(labelValue('Options', '-g, --global    Install to global agent config (~/.agent/skills/)'));
+  printLine(labelValue('Options', '-g, --global    Install to global agent config (~/.agents/skills/)'));
   printLine(labelValue('       ', '--force         Re-install even if already installed'));
   printLine(labelValue('       ', '--dry-run       Show what would be done without making changes'));
   printLine(labelValue('       ', '-h, --help      Show this help message'));

package/src/dashboard/public/index.html

@@ -9,9 +9,8 @@
     <!-- Marked.js for Markdown parsing -->
     <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
     <!-- Vis-Network for Interactive Graphs -->
-    <script type="text/javascript" src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
-    <!-- Chart.js for Heatmap -->
-    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/vis-network/9.1.9/standalone/umd/vis-network.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.9.1/chart.min.js"></script>
     <style>
         :root {
             --bg-color: #0d0d0d;
@@ -491,9 +490,12 @@
                             totalFiles++;
                             if (isDanger) {
                                 dangerFilesCount++;
-                                dangerListHTML += `<div style="padding: 12px 16px; background: var(--bg-color); border: 1px solid var(--glass-border); border-radius: 8px; margin-bottom: 8px; display: flex; justify-content: space-between; align-items: center;">
-                                    <span style="font-family: var(--font-mono); font-size: 13px; color: var(--text-main);">${node.path}</span>
-                                    <span style="font-size: 10px; color: var(--text-muted); border: 1px solid var(--glass-border); padding: 4px 8px; border-radius: 20px;">Flagged</span>
+                                dangerListHTML += `<div style="padding: 12px 16px; background: var(--bg-color); border: 1px solid var(--glass-border); border-radius: 8px; margin-bottom: 12px; display: flex; flex-direction: column; gap: 8px;">
+                                    <div style="display: flex; justify-content: space-between; align-items: center;">
+                                        <span style="font-family: var(--font-mono); font-size: 13px; color: var(--text-main);">${node.path}</span>
+                                        <span style="font-size: 10px; color: var(--danger); border: 1px solid var(--glass-border); padding: 4px 8px; border-radius: 20px;">Flagged</span>
+                                    </div>
+                                    <div style="font-size: 12px; color: var(--text-muted); line-height: 1.4;">${node.dangerReason || 'Legacy anti-pattern detected.'}</div>
                                 </div>`;
                             }
                         }
@@ -611,22 +613,89 @@ ${steps}
         }
 
         function renderGraph() {
-            if(networkInstance) return; // already rendered
-            
-            // Mock graph data, in a real scenario we'd parse .docs/
-            const nodes = new vis.DataSet([
-                { id: 1, label: 'Client App', color: '#00ffaa', shape: 'box' },
-                { id: 2, label: 'API Gateway', color: '#00ffaa', shape: 'box' },
-                { id: 3, label: 'Auth Service', color: '#ff4757', shape: 'box' },
-                { id: 4, label: 'Database', color: '#f1f5f9', shape: 'database' },
-            ]);
-            const edges = new vis.DataSet([
-                { from: 1, to: 2, arrows: 'to' },
-                { from: 2, to: 3, arrows: 'to', label: 'verify token' },
-                { from: 3, to: 4, arrows: 'to' },
-            ]);
-            
+            if (networkInstance) return; // Already rendered
+
             const container = document.getElementById('network-graph');
+            if (typeof vis === 'undefined') {
+                container.innerHTML = '<div style="padding: 40px; text-align: center; color: var(--danger);">Failed to load graph library. Please check your internet connection or use a local build.</div>';
+                return;
+            }
+
+            // Dynamic Mermaid Parser
+            let nodesMap = new Map();
+            let edgesList = [];
+            let nodeIdCounter = 1;
+
+            function parseNode(str) {
+                const match = str.trim().match(/^([a-zA-Z0-9_-]+)(.*)$/);
+                if (!match) return null;
+                const rawId = match[1];
+                let label = rawId;
+                let shape = 'box';
+                const rest = match[2].trim();
+                if (rest) {
+                    const labelMatch = rest.match(/[\[\(\{]+(.*?)[\]\}\)]+/);
+                    if (labelMatch) label = labelMatch[1].replace(/["']/g, '');
+                    if (rest.includes('[((') || rest.includes('[([')) shape = 'database';
+                    else if (rest.includes('{')) shape = 'diamond';
+                    else if (rest.includes('((')) shape = 'ellipse';
+                }
+                return { rawId, label, shape };
+            }
+
+            docsData.forEach(doc => {
+                const mermaidRegex = /```mermaid\s+([\s\S]*?)```/g;
+                let match;
+                while ((match = mermaidRegex.exec(doc.content)) !== null) {
+                    const lines = match[1].split('\n');
+                    lines.forEach(line => {
+                        let l = line.trim();
+                        if (!l || l.startsWith('graph') || l.startsWith('flowchart') || l.startsWith('subgraph') || l.startsWith('end')) return;
+
+                        const parts = l.split('-->');
+                        if (parts.length >= 2) {
+                            let fromPart = parts[0].trim();
+                            let toPart = parts.slice(1).join('-->').trim();
+                            
+                            let edgeLabel = '';
+                            if (toPart.startsWith('|')) {
+                                const pipeEnd = toPart.indexOf('|', 1);
+                                if (pipeEnd > -1) {
+                                    edgeLabel = toPart.substring(1, pipeEnd).trim();
+                                    toPart = toPart.substring(pipeEnd + 1).trim();
+                                }
+                            }
+
+                            const fNode = parseNode(fromPart);
+                            const tNode = parseNode(toPart);
+
+                            if (fNode && tNode) {
+                                if (!nodesMap.has(fNode.rawId)) {
+                                    nodesMap.set(fNode.rawId, { id: nodeIdCounter++, label: fNode.label, shape: fNode.shape, color: { background: '#151515', border: '#2a2a2a' } });
+                                }
+                                if (!nodesMap.has(tNode.rawId)) {
+                                    nodesMap.set(tNode.rawId, { id: nodeIdCounter++, label: tNode.label, shape: tNode.shape, color: { background: '#151515', border: '#2a2a2a' } });
+                                }
+
+                                edgesList.push({
+                                    from: nodesMap.get(fNode.rawId).id,
+                                    to: nodesMap.get(tNode.rawId).id,
+                                    arrows: 'to',
+                                    label: edgeLabel
+                                });
+                            }
+                        }
+                    });
+                }
+            });
+
+            if (nodesMap.size === 0) {
+                container.innerHTML = '<div style="padding: 40px; text-align: center; color: var(--text-muted);">No Mermaid architecture graphs found in .docs/ files. Run the project-scanner skill first.</div>';
+                return;
+            }
+
+            const nodes = new vis.DataSet(Array.from(nodesMap.values()));
+            const edges = new vis.DataSet(edgesList);
             const data = { nodes, edges };
             const options = {
                 nodes: { 
@@ -735,8 +804,15 @@ ${steps}
                             },
                             response: [{
                                 name: "Success",
+                                originalRequest: {
+                                    method: ep.method,
+                                    header: [{ key: "Authorization", value: "Bearer {{token}}" }, { key: "Content-Type", value: "application/json" }],
+                                    body: ep.method !== 'GET' ? { mode: "raw", raw: JSON.stringify(mock, null, 2) } : undefined,
+                                    url: { raw: `{{baseUrl}}/${pathArr.join('/')}`, host: ["{{baseUrl}}"], path: pathArr }
+                                },
                                 status: "OK",
                                 code: 200,
+                                _postman_previewlanguage: "json",
                                 header: [{ key: "Content-Type", value: "application/json" }],
                                 body: JSON.stringify({ success: true, data: mock }, null, 2)
                             }]
@@ -751,8 +827,15 @@ ${steps}
                             },
                             response: [{
                                 name: "Bad Request",
+                                originalRequest: {
+                                    method: ep.method,
+                                    header: [{ key: "Authorization", value: "Bearer {{token}}" }, { key: "Content-Type", value: "application/json" }],
+                                    body: ep.method !== 'GET' ? { mode: "raw", raw: "{}" } : undefined,
+                                    url: { raw: `{{baseUrl}}/${pathArr.join('/')}`, host: ["{{baseUrl}}"], path: pathArr }
+                                },
                                 status: "Bad Request",
                                 code: 400,
+                                _postman_previewlanguage: "json",
                                 header: [{ key: "Content-Type", value: "application/json" }],
                                 body: JSON.stringify({ success: false, error: { code: "VALIDATION_ERROR", message: "Invalid parameters provided" } }, null, 2)
                             }]
@@ -766,8 +849,14 @@ ${steps}
                             },
                             response: [{
                                 name: "Unauthorized",
+                                originalRequest: {
+                                    method: ep.method,
+                                    header: [], // No auth
+                                    url: { raw: `{{baseUrl}}/${pathArr.join('/')}`, host: ["{{baseUrl}}"], path: pathArr }
+                                },
                                 status: "Unauthorized",
                                 code: 401,
+                                _postman_previewlanguage: "json",
                                 header: [{ key: "Content-Type", value: "application/json" }],
                                 body: JSON.stringify({ success: false, error: { code: "UNAUTHORIZED", message: "Missing or invalid token" } }, null, 2)
                             }]

package/src/dashboard/server.js

@@ -45,28 +45,60 @@ const server = http.createServer((req, res) => {
   // API Route: Get File Tree (for Heatmap)
   if (req.url === '/api/tree' && req.method === 'GET') {
     res.setHeader('Content-Type', 'application/json');
-    const ignoreDirs = ['node_modules', '.git', '.docs', '.claude', '.cursor', '.codex', 'dist', 'build'];
     
-    function scanDir(dir, base = '') {
-      let results = [];
-      try {
-        const items = fs.readdirSync(dir);
-        for (const item of items) {
-          if (ignoreDirs.includes(item) || item.startsWith('.')) continue;
-          const fullPath = path.join(dir, item);
-          const relPath = path.join(base, item);
-          const stat = fs.statSync(fullPath);
-          if (stat.isDirectory()) {
-            results.push({ name: item, type: 'dir', path: relPath, children: scanDir(fullPath, relPath) });
-          } else {
-            results.push({ name: item, type: 'file', path: relPath });
-          }
+    const getDirectoryTree = (dirPath, relativePath = '') => {
+      const items = fs.readdirSync(dirPath);
+      let result = [];
+      
+      for (const item of items) {
+        if (['node_modules', '.git', '.docs', '.agents', '.spark'].includes(item)) continue;
+        
+        const fullPath = path.join(dirPath, item);
+        const itemRelativePath = path.join(relativePath, item);
+        const stat = fs.statSync(fullPath);
+        
+        let isDanger = false;
+        let dangerReason = '';
+        
+        const lowerItem = item.toLowerCase();
+        if (lowerItem.includes('controller')) {
+            isDanger = true;
+            dangerReason = 'Anti-Pattern: "God Object" tendency. Move business logic to specific Domain Services instead of Controllers.';
+        } else if (lowerItem.includes('utils')) {
+            isDanger = true;
+            dangerReason = 'Legacy Trap: "Utils" folders become untracked dumping grounds for dead code. Use specific domain modules.';
+        } else if (lowerItem.includes('helper')) {
+            isDanger = true;
+            dangerReason = 'Legacy Trap: "Helpers" lack clear boundaries and violate single responsibility principles.';
+        } else if (lowerItem.includes('api') && stat.isDirectory()) {
+            isDanger = true;
+            dangerReason = 'Anti-Pattern: Generic "API" folders often lead to poor separation of concerns. Group by feature/domain instead.';
         }
-      } catch (e) {}
-      return results;
-    }
+
+        if (stat.isDirectory()) {
+          const children = getDirectoryTree(fullPath, itemRelativePath);
+          result.push({
+            name: item,
+            path: itemRelativePath,
+            type: 'dir',
+            isDanger,
+            dangerReason,
+            children
+          });
+        } else {
+          result.push({
+            name: item,
+            path: itemRelativePath,
+            type: 'file',
+            isDanger,
+            dangerReason
+          });
+        }
+      }
+      return result;
+    };
     
-    return res.end(JSON.stringify({ tree: scanDir(process.cwd()) }));
+    return res.end(JSON.stringify({ tree: getDirectoryTree(process.cwd()) }));
   }
 
   // API Route: Get SPARK Readme (for Guide)
@@ -97,7 +129,7 @@ const server = http.createServer((req, res) => {
     }
     
     // 2. Custom skills
-    const customDir = path.join(process.cwd(), '.agent', 'skills');
+    const customDir = path.join(process.cwd(), '.agents', 'skills');
     if (fs.existsSync(customDir)) {
       try {
         const items = fs.readdirSync(customDir);
@@ -119,8 +151,8 @@ const server = http.createServer((req, res) => {
       }
       
       // Save to a safe, user-level directory that SPARK updates won't touch
-      // The Anthropic standard allows putting skills in .agent/skills/
-      const customSkillsDir = path.join(process.cwd(), '.agent', 'skills', data.name);
+      // The Anthropic/Gemini standard allows putting skills in .agents/skills/
+      const customSkillsDir = path.join(process.cwd(), '.agents', 'skills', data.name);
       
       try {
         fs.mkdirSync(customSkillsDir, { recursive: true });