@abarcenas/ai-workflow-template 1.40.0 → 1.43.0

package/memory-bank/.vocabulary.json

@@ -9,50 +9,134 @@
     "task": "Individual task tracking (tasks/TASK*.md)",
     "decision": "ADR-style architecture/technical decisions"
   },
-
   "tags": {
     "agent_roles": [
-      "designer", "architect", "researcher", "coder", "implementer",
-      "tester", "reviewer", "tracker", "deployer", "orchestrator"
+      "designer",
+      "architect",
+      "researcher",
+      "coder",
+      "implementer",
+      "tester",
+      "reviewer",
+      "tracker",
+      "deployer",
+      "orchestrator"
     ],
     "workflow": [
-      "bootstrap", "setup", "configuration", "migration", "refactor",
-      "tdd", "feature-pipeline", "onboarding", "normalization",
-      "research", "spike", "implementation", "implementation-planning",
+      "bootstrap",
+      "setup",
+      "configuration",
+      "migration",
+      "refactor",
+      "tdd",
+      "feature-pipeline",
+      "onboarding",
+      "normalization",
+      "research",
+      "spike",
+      "implementation",
+      "implementation-planning",
       "documentation"
     ],
     "memory_ops": [
-      "decision", "discovery", "status-update", "task-plan", "retrospective",
-      "bug-fix", "verification"
+      "decision",
+      "discovery",
+      "status-update",
+      "task-plan",
+      "retrospective",
+      "bug-fix",
+      "verification"
     ],
     "topic": [
-      "knowledgebase", "pgvector", "mcp", "embeddings", "dotenv",
-      "chunk-parser", "agent-exercise"
+      "agent-exercise",
+      "chunk-parser",
+      "dotenv",
+      "embeddings",
+      "feature-vocab-sync",
+      "fix-kb-registerproject",
+      "float32array",
+      "knowledgebase",
+      "learned-knowledge",
+      "mcp",
+      "package-structure",
+      "pgvector",
+      "pre-commit",
+      "readme",
+      "vocabulary"
     ]
   },
-
   "entity_patterns": {
-    "vitest":            ["vitest", "vitest\\.config", "@vitest\\/coverage"],
-    "playwright":        ["playwright", "@playwright", "browser.*test"],
-    "graphify":          ["graphify", "knowledge graph", "graph\\.json"],
-    "memory-bank":       ["memory-bank", "memory bank", "activeContext", "systemPatterns"],
-    "husky":             ["husky", "pre-commit", "git hook"],
-    "tdd-orchestrator":  ["tdd orchestrator", "RED.*GREEN.*REFACTOR"],
-    "mcp-server":        ["mcp", "modelcontextprotocol", "stdio", "mcp server"],
-    "sqlite-vec":        ["sqlite-vec", "sqlite.vec", "better-sqlite3"],
-    "transformers.js":   ["@xenova\\/transformers", "transformers\\.js", "all-MiniLM"],
-    "opencode":          ["opencode", "OpenCode", "open code"],
-    "npm":               ["npm", "npm package", "npm install"]
+    "vitest": [
+      "vitest",
+      "vitest\\.config",
+      "@vitest\\/coverage"
+    ],
+    "playwright": [
+      "playwright",
+      "@playwright",
+      "browser.*test"
+    ],
+    "graphify": [
+      "graphify",
+      "knowledge graph",
+      "graph\\.json"
+    ],
+    "memory-bank": [
+      "memory-bank",
+      "memory bank",
+      "activeContext",
+      "systemPatterns"
+    ],
+    "husky": [
+      "husky",
+      "pre-commit",
+      "git hook"
+    ],
+    "tdd-orchestrator": [
+      "tdd orchestrator",
+      "RED.*GREEN.*REFACTOR"
+    ],
+    "mcp-server": [
+      "mcp",
+      "modelcontextprotocol",
+      "stdio",
+      "mcp server"
+    ],
+    "sqlite-vec": [
+      "sqlite-vec",
+      "sqlite.vec",
+      "better-sqlite3"
+    ],
+    "transformers.js": [
+      "@xenova\\/transformers",
+      "transformers\\.js",
+      "all-MiniLM"
+    ],
+    "opencode": [
+      "opencode",
+      "OpenCode",
+      "open code"
+    ],
+    "npm": [
+      "npm",
+      "npm package",
+      "npm install"
+    ]
   },
-
   "file_category_map": {
-    "projectbrief":     "brief",
-    "productContext":   "product",
-    "systemPatterns":   "architecture",
-    "techContext":      "tech",
-    "activeContext":    "context",
-    "progress":         "progress"
+    "projectbrief": "brief",
+    "productContext": "product",
+    "systemPatterns": "architecture",
+    "techContext": "tech",
+    "activeContext": "context",
+    "progress": "progress"
   },
-
-  "doc_types": ["spike", "architecture", "configuration", "orchestrator-log", "tracker-log", "decision"]
+  "doc_types": [
+    "spike",
+    "architecture",
+    "configuration",
+    "orchestrator-log",
+    "tracker-log",
+    "decision"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.40.0",
+  "version": "1.43.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
   "bin": {

package/scripts/mcp-knowledgebase-server.js

@@ -20,17 +20,23 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+
+// Load .env file into process.env before any configuration reads
+import 'dotenv/config';
+
 import {
   search,
   upsertChunks,
   chunkLearnedKnowledge,
   getStats,
   listProjects,
+  registerProject,
   getPool,
   closePool,
 } from './knowledgebase-index.js';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const server = new Server(
   {
@@ -68,7 +74,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           threshold: {
             type: 'number',
-            default: 0.6,
+            default: 0.1,
             description: 'Minimum similarity threshold (0.0–1.0). Higher values return fewer but more relevant results.',
           },
           limit: {
@@ -126,18 +132,65 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   ],
 }));
 
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Redact connection-string credentials from an error message.
+ *
+ * Every postgres:// or postgresql:// URL token in the message has its
+ * userinfo credentials replaced with *** and its query string (or fragment)
+ * replaced with ?*** / #***, while the host and path are preserved verbatim
+ * (e.g. postgres://user:secret@host:5432/kb?password=hunter2 →
+ * postgres://***@host:5432/kb?***). Messages without a URL token are returned
+ * unchanged so generic errors (e.g. "Unknown tool: ...") stay readable — the
+ * engine helper returns '***' for non-URLs, which would hide every error
+ * message.
+ *
+ * Unlike the engine helper (knowledgebase-index.js:62) — which fails closed
+ * by returning '***' when `new URL()` throws — this helper FAILS CLOSED on
+ * unparseable tokens by using a pure regex instead of URL parsing: libpq
+ * unix-socket authorities such as postgres://user:secret@/var/run/postgresql
+ * (or postgresql://user:secret@/tmp?host=/tmp) make `new URL()` throw, so a
+ * parse-based helper would return the message unchanged and leak the
+ * credentials. The regex strips the userinfo and the query/fragment from
+ * EVERY token and preserves the host/path even when the URL cannot be parsed.
+ *
+ * @param {string} message
+ * @returns {string}
+ */
+function redactConnectionString(message) {
+  if (typeof message !== 'string' || message.length === 0) return message;
+  return message.replace(
+    /(postgres(?:ql)?:\/\/)([^/\s]+)@([^?#\s]*)([?#][^\s]*)?/gi,
+    (match, scheme, userinfo, hostAndPath, queryOrFragment) =>
+      `${scheme}***@${hostAndPath}${queryOrFragment ? queryOrFragment[0] + '***' : ''}`
+  );
+}
+
 // ── Handle tool calls ────────────────────────────────────────────────
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+/**
+ * Handle an MCP tool call.
+ *
+ * Exported for testability — the stdio bootstrap (main) is guarded to
+ * direct-run only, so tests can import this handler without opening a
+ * stdio transport or a database connection.
+ * @param {{ params: { name: string, arguments: Record<string, any> } }} request
+ * @returns {Promise<{ content: Array<{ type: string, text: string }>, isError?: boolean }>}
+ */
+export async function handleToolCall(request) {
   const { name, arguments: args } = request.params;
 
   try {
     switch (name) {
       case 'knowledgebase_search': {
+        // projectId is an optional filter — a whitespace-only value is dropped
+        // to match-all (graceful degradation, mirroring the INDEX handler's
+        // trim/validate parity) and the trimmed value is passed to the engine.
         const results = await search(args.query, {
-          project_id: args.projectId || undefined,
-          threshold: args.threshold || 0.6,
-          limit: args.limit || 5,
+          project_id: args.projectId?.trim() || undefined,
+          threshold: args.threshold ?? 0.1,
+          limit: args.limit ?? 5,
         });
 
         if (results.length === 0) {
@@ -176,7 +229,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'knowledgebase_index': {
         const projectId = args.projectId;
-        if (!projectId) {
+        if (!projectId?.trim()) {
           return {
             content: [{
               type: 'text',
@@ -185,6 +238,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             isError: true,
           };
         }
+        const pid = projectId.trim();
 
         let content = args.content;
         if (!content) {
@@ -209,25 +263,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
         }
 
-        const chunks = chunkLearnedKnowledge(content, projectId);
+        const chunks = chunkLearnedKnowledge(content, pid);
         if (chunks.length === 0) {
           return {
             content: [{
               type: 'text',
-              text: `No valid knowledge chunks found for project "${projectId}". ` +
+              text: `No valid knowledge chunks found for project "${pid}". ` +
                 'Ensure the content contains "## Session:" headers with ' +
                 '"**New knowledge:**" sections.',
             }],
           };
         }
 
+        // Register/update the project in the projects table (idempotent upsert)
+        await registerProject(pid, pid);
+
         const result = await upsertChunks(chunks);
         return {
           content: [{
             type: 'text',
             text:
               `Indexed ${result.inserted} chunks, updated ${result.updated}, ` +
-              `skipped ${result.skipped} for project "${projectId}".`,
+              `skipped ${result.skipped} for project "${pid}".`,
           }],
         };
       }
@@ -303,12 +360,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return {
       content: [{
         type: 'text',
-        text: `Error: ${err.message}`,
+        text: `Error: ${redactConnectionString(err.message)}`,
       }],
       isError: true,
     };
   }
-});
+}
+
+server.setRequestHandler(CallToolRequestSchema, handleToolCall);
 
 // ── Start server ─────────────────────────────────────────────────────
 
@@ -318,13 +377,24 @@ async function main() {
   console.error('[knowledgebase-mcp] Server started via stdio transport');
 }
 
-process.on('SIGTERM', () => {
-  console.error('[knowledgebase-mcp] SIGTERM received, closing pool');
-  closePool().catch(() => {});
-  process.exit(0);
-});
+/**
+ * Only start the stdio server when this file is executed directly
+ * (node scripts/mcp-knowledgebase-server.js). When the module is imported
+ * — e.g. by tests exercising the exported handleToolCall — no stdio
+ * transport is opened and the process can exit cleanly.
+ */
+const isDirectRun =
+  process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 
-main().catch((err) => {
-  console.error('[knowledgebase-mcp] Fatal error:', err);
-  process.exit(1);
-});
+if (isDirectRun) {
+  process.on('SIGTERM', () => {
+    console.error('[knowledgebase-mcp] SIGTERM received, closing pool');
+    closePool().catch(() => {});
+    process.exit(0);
+  });
+
+  main().catch((err) => {
+    console.error('[knowledgebase-mcp] Fatal error:', err);
+    process.exit(1);
+  });
+}