@kkelly-offical/kkcode 0.1.2

package/src/knowledge/java.txt

@@ -0,0 +1,9 @@
+Java / Spring Boot conventions for this project:
+- Spring Boot with @SpringBootApplication entry point
+- @RestController for API endpoints, @Service for business logic
+- @Repository with Spring Data JPA for data access
+- Constructor injection (not field injection) for dependencies
+- Records for DTOs, entities with @Entity annotation
+- Validation: @Valid + jakarta.validation annotations
+- Testing: JUnit 5 + Mockito, @SpringBootTest for integration
+- Maven or Gradle for build, application.yml for config

package/src/knowledge/kotlin.txt

@@ -0,0 +1,10 @@
+Kotlin conventions for this project:
+- Null safety: use ?, ?., ?:, let, require, check
+- Data classes for DTOs and value objects
+- Sealed classes for restricted hierarchies and state machines
+- Coroutines: suspend functions, Flow for reactive streams
+- Extension functions for utility methods
+- Scope functions: let, run, with, apply, also
+- Android: Jetpack Compose for UI, ViewModel + StateFlow for state
+- Spring Boot: @RestController, @Service with constructor injection
+- Testing: JUnit 5 + MockK, kotlinx-coroutines-test for coroutines

package/src/knowledge/loader.mjs

@@ -0,0 +1,125 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const KNOWLEDGE_DIR = path.dirname(fileURLToPath(import.meta.url))
+const cache = new Map()
+
+// Framework → knowledge files mapping
+const FRAMEWORK_MAP = {
+  vue: ["vue.txt"],
+  react: ["react.txt"],
+  next: ["next.txt", "react.txt"],
+  nuxt: ["nuxt.txt", "vue.txt"],
+  sveltekit: ["svelte.txt"],
+  svelte: ["svelte.txt"],
+  angular: [],
+  astro: [],
+  solid: [],
+  "react-native": ["react-native.txt", "react.txt"],
+  electron: ["electron.txt"],
+  flutter: ["flutter.txt"],
+  laravel: ["php.txt"],
+  rails: ["ruby.txt"],
+}
+
+// Backend frameworks → language knowledge
+const BACKEND_FRAMEWORK_LANG = {
+  fastapi: "python.txt",
+  django: "python.txt",
+  flask: "python.txt",
+  gin: "go.txt",
+  fiber: "go.txt",
+  echo: "go.txt",
+  actix: "rust.txt",
+  axum: "rust.txt",
+  rocket: "rust.txt",
+  spring: "java.txt",
+  aspnet: "dotnet.txt",
+  laravel: "php.txt",
+  rails: "ruby.txt",
+}
+
+// Language → knowledge file (for non-JS ecosystems)
+const LANGUAGE_MAP = {
+  go: "go.txt",
+  python: "python.txt",
+  rust: "rust.txt",
+  java: "java.txt",
+  kotlin: "kotlin.txt",
+  php: "php.txt",
+  ruby: "ruby.txt",
+  dart: "flutter.txt",
+  swift: "swift.txt",
+  cpp: "cpp.txt",
+  dotnet: "dotnet.txt",
+}
+
+// Project type → scenario knowledge
+const TYPE_MAP = {
+  backend: ["api-design.txt"],
+  fullstack: ["api-design.txt"],
+}
+
+// Feature → knowledge file
+const FEATURE_MAP = {
+  tailwind: "tailwind.txt",
+  graphql: "graphql.txt",
+  docker: "docker.txt",
+  electron: "electron.txt",
+  "react-native": "react-native.txt",
+}
+
+/**
+ * Load knowledge files matching the detected project context.
+ * Returns concatenated knowledge text, or empty string.
+ */
+export async function loadKnowledge({ framework, language, projectType, hasTests, features = [] }) {
+  const files = new Set()
+
+  // Tier 1: Framework knowledge
+  if (framework) {
+    for (const f of (FRAMEWORK_MAP[framework] || [])) files.add(f)
+    // Backend framework → language file
+    if (BACKEND_FRAMEWORK_LANG[framework]) files.add(BACKEND_FRAMEWORK_LANG[framework])
+  }
+
+  // Tier 1: Language knowledge
+  if (language === "typescript") files.add("typescript.txt")
+  if (!framework && language === "javascript") files.add("node.txt")
+  // Non-JS languages
+  if (LANGUAGE_MAP[language] && !files.has(LANGUAGE_MAP[language])) {
+    files.add(LANGUAGE_MAP[language])
+  }
+
+  // Tier 2: Scenario knowledge
+  if (projectType && TYPE_MAP[projectType]) {
+    for (const f of TYPE_MAP[projectType]) files.add(f)
+  }
+  if (hasTests) files.add("testing.txt")
+
+  // Tier 2: Feature knowledge
+  for (const feat of features) {
+    if (FEATURE_MAP[feat]) files.add(FEATURE_MAP[feat])
+  }
+
+  // Load and concatenate
+  const sections = []
+  for (const file of files) {
+    const text = await loadFile(file)
+    if (text) sections.push(text)
+  }
+  return sections.length ? sections.join("\n\n") : ""
+}
+
+async function loadFile(name) {
+  if (cache.has(name)) return cache.get(name)
+  try {
+    const text = (await readFile(path.join(KNOWLEDGE_DIR, name), "utf8")).trim()
+    cache.set(name, text)
+    return text
+  } catch {
+    cache.set(name, "")
+    return ""
+  }
+}

package/src/knowledge/next.txt

@@ -0,0 +1,8 @@
+Next.js App Router conventions:
+- Server Components by default, 'use client' only for interactivity
+- app/ directory: layout.tsx, page.tsx, loading.tsx, error.tsx
+- Server Actions with 'use server' for mutations
+- Data fetching: async Server Components, no useEffect for data
+- next/image for images, next/link for navigation, next/font for fonts
+- Route Handlers in app/api/ for API endpoints
+- Metadata API for SEO: export const metadata or generateMetadata()

package/src/knowledge/node.txt

@@ -0,0 +1,8 @@
+Node.js conventions for this project:
+- ESM modules ("type": "module" in package.json)
+- Async/await for all I/O, avoid callback patterns
+- Error handling: try/catch with specific error types
+- Environment: dotenv for config, never hardcode secrets
+- Logging: structured logging (pino or winston)
+- Validation: zod or joi for input validation
+- File structure: src/ with clear separation of concerns

package/src/knowledge/nuxt.txt

@@ -0,0 +1,9 @@
+Nuxt 3 conventions for this project:
+- Auto-imports: no need to import ref, computed, useState, etc.
+- Pages auto-register routes based on file structure (pages/)
+- Components auto-register based on file name (components/)
+- Composables auto-imported from composables/ directory
+- useFetch() or useAsyncData() for SSR-friendly data fetching
+- definePageMeta() for page-level metadata and middleware
+- server/api/ for API routes with defineEventHandler()
+- useState('key', () => default) for SSR-safe shared state

package/src/knowledge/php.txt

@@ -0,0 +1,10 @@
+PHP/Laravel conventions for this project:
+- MVC architecture: Controllers, Models (Eloquent), Blade views
+- Routing: routes/web.php for web, routes/api.php for API
+- Eloquent ORM: relationships, scopes, accessors/mutators
+- Migrations for database schema, Seeders for test data
+- Form Requests for validation, Resources for API responses
+- Middleware for authentication, CORS, rate limiting
+- Artisan commands: php artisan make:model/controller/migration
+- Composer for dependency management
+- Testing: PHPUnit with Feature and Unit test directories

package/src/knowledge/python.txt

@@ -0,0 +1,10 @@
+Python conventions for this project:
+- Type hints on all function signatures
+- Pydantic models for data validation and serialization
+- async/await for I/O-bound operations
+- Virtual environment (venv or poetry)
+- Project structure: src/<package>/ with __init__.py
+- Testing: pytest with fixtures, parametrize for variants
+- Linting: ruff for formatting and linting
+- Logging: use logging module, not print()
+- Error handling: specific exceptions, not bare except

package/src/knowledge/react-native.txt

@@ -0,0 +1,10 @@
+React Native conventions for this project:
+- Functional components with hooks, same as React
+- Navigation: React Navigation (@react-navigation/native)
+- Styling: StyleSheet.create(), flexbox layout (default column)
+- Platform-specific: Platform.OS, Platform.select(), .ios.tsx/.android.tsx
+- Native modules: use Expo SDK or react-native-* community packages
+- State: React Context, Zustand, or Redux Toolkit
+- Lists: FlatList for long lists (not ScrollView + map)
+- Images: require() for local, { uri } for remote, use caching
+- Testing: Jest + React Native Testing Library

package/src/knowledge/react.txt

@@ -0,0 +1,9 @@
+React conventions for this project:
+- Functional components only, TypeScript interfaces for props
+- Hooks: useState, useEffect, useMemo, useCallback, useRef
+- Custom hooks in hooks/ directory, prefixed with "use"
+- React Router v6: createBrowserRouter, useParams, useNavigate
+- State: local useState, complex useReducer, global Context/Zustand
+- Prefer named exports, one component per file
+- Memoize expensive components with React.memo()
+- Error boundaries for fault isolation

package/src/knowledge/ruby.txt

@@ -0,0 +1,11 @@
+Ruby/Rails conventions for this project:
+- MVC: app/controllers/, app/models/, app/views/
+- Convention over configuration: naming drives behavior
+- ActiveRecord for ORM: migrations, associations, validations, scopes
+- RESTful routes: resources :users in config/routes.rb
+- Strong parameters for mass assignment protection
+- Concerns for shared model/controller logic
+- Background jobs: Sidekiq or ActiveJob
+- Testing: RSpec preferred, FactoryBot for test data
+- Gems via Bundler, Gemfile for dependency management
+- Ruby style: snake_case methods, 2-space indent, no semicolons

package/src/knowledge/rust.txt

@@ -0,0 +1,9 @@
+Rust conventions for this project:
+- Ownership and borrowing: prefer references over cloning
+- Error handling: Result<T, E> with ? operator, thiserror for custom errors
+- Traits for abstraction, impl blocks for methods
+- Pattern matching with match and if let
+- Cargo workspace for multi-crate projects
+- Testing: #[cfg(test)] mod tests, #[test] functions
+- Naming: snake_case for functions/variables, PascalCase for types
+- Use clippy lints and rustfmt for code quality

package/src/knowledge/svelte.txt

@@ -0,0 +1,9 @@
+SvelteKit conventions for this project:
+- Svelte 5 runes: $state(), $derived(), $effect(), $props()
+- File-based routing: src/routes/+page.svelte, +layout.svelte
+- Server data loading: +page.server.ts with export const load
+- Access data in page: let { data } = $props()
+- <style> is scoped by default in Svelte components
+- Form actions for mutations: +page.server.ts export const actions
+- $lib alias for src/lib/ imports
+- Use <script lang="ts"> for TypeScript

package/src/knowledge/swift.txt

@@ -0,0 +1,10 @@
+Swift conventions for this project:
+- SwiftUI: declarative UI with @State, @Binding, @ObservedObject, @EnvironmentObject
+- MVVM architecture: View, ViewModel (ObservableObject), Model
+- Combine framework for reactive programming
+- Structured concurrency: async/await, Task, AsyncSequence
+- Protocol-oriented programming over class inheritance
+- Optionals: guard let, if let, nil coalescing (??)
+- SPM (Swift Package Manager) for dependencies
+- Naming: camelCase for properties/methods, PascalCase for types
+- Testing: XCTest framework, XCTAssert for assertions

package/src/knowledge/tailwind.txt

@@ -0,0 +1,10 @@
+Tailwind CSS conventions:
+- Utility-first: compose styles with utility classes, avoid custom CSS
+- Responsive: mobile-first with sm:, md:, lg:, xl:, 2xl: prefixes
+- Dark mode: dark: prefix with class or media strategy
+- Component patterns: extract repeated patterns with @apply in CSS or component abstraction
+- Spacing scale: p-4 = 1rem, m-2 = 0.5rem (4px base)
+- Colors: bg-blue-500, text-gray-900, use project's color palette
+- Layout: flex, grid, container mx-auto, gap utilities
+- Customization: tailwind.config.js for theme extension
+- Avoid: inline styles, arbitrary values when a utility exists

package/src/knowledge/testing.txt

@@ -0,0 +1,8 @@
+Testing conventions:
+- Test file next to source or in __tests__/ directory
+- Name: [module].test.ts / test_[module].py / [module]_test.go
+- Structure: Arrange-Act-Assert (AAA) pattern
+- Cover: happy path, edge cases, error conditions
+- Mock external dependencies, not internal logic
+- Integration tests for API endpoints and database queries
+- Avoid testing implementation details, test behavior

package/src/knowledge/typescript.txt

@@ -0,0 +1,8 @@
+TypeScript conventions:
+- Strict mode enabled (strict: true in tsconfig)
+- Prefer interfaces over type aliases for object shapes
+- Use discriminated unions for state machines
+- Avoid 'any', use 'unknown' + type guards instead
+- Utility types: Partial<T>, Pick<T,K>, Omit<T,K>, Record<K,V>
+- Enums: prefer const enums or string literal unions
+- Generic constraints: <T extends Base> for bounded generics

package/src/knowledge/vue.txt

@@ -0,0 +1,9 @@
+Vue 3 conventions for this project:
+- Single-file components with <script setup lang="ts">
+- Composition API: ref(), reactive(), computed(), watch()
+- Props: defineProps<T>(), Emits: defineEmits<T>()
+- Pinia stores with setup syntax: defineStore('name', () => { ... })
+- Vue Router: createRouter + createWebHistory, lazy routes
+- <style scoped> by default, CSS variables for theming
+- Component naming: PascalCase files, kebab-case in templates
+- Composables in composables/ directory, prefixed with "use"

package/src/mcp/client-http.mjs

@@ -0,0 +1,157 @@
+import { McpError } from "../core/errors.mjs"
+import { EventBus } from "../core/events.mjs"
+import { EVENT_TYPES } from "../core/constants.mjs"
+
+function timeoutSignal(ms, parentSignal = null) {
+  const own = AbortSignal.timeout(ms)
+  if (!parentSignal) return own
+  return AbortSignal.any([parentSignal, own])
+}
+
+function classifyHttpError(error, status = null) {
+  const msg = String(error?.message || error || "")
+  if (msg.includes("AbortError") || msg.includes("timeout") || msg.includes("abort")) return "timeout"
+  if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) return "connection_refused"
+  if (status && status >= 500) return "server_crash"
+  if (status && status >= 400) return "bad_response"
+  return "unknown"
+}
+
+function normalizeToolResult(result, serverName, toolName) {
+  if (result?.isError) {
+    const text = Array.isArray(result.content)
+      ? result.content.map((item) => item?.text || "").join("\n").trim()
+      : ""
+    throw new McpError(text || "mcp tool returned isError", {
+      reason: "bad_response",
+      server: serverName,
+      action: `tools/call:${toolName}`,
+      phase: "request"
+    })
+  }
+  const content = Array.isArray(result?.content) ? result.content : null
+  const contentText = content
+    ? content.map((item) => (typeof item?.text === "string" ? item.text : "")).join("\n").trim()
+    : ""
+  const output =
+    contentText ||
+    (typeof result?.output === "string" ? result.output : "") ||
+    (typeof result === "string" ? result : JSON.stringify(result))
+  return content ? { output, raw: result, content } : { output, raw: result }
+}
+
+async function requestJson({ serverName, method, url, body = null, timeoutMs = 10000, headers = {}, signal = null }) {
+  const action = method === "GET" ? url.split("/").pop() : body?.args ? "call_tool" : "request"
+  const startedAt = Date.now()
+  let status = null
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...headers
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: timeoutSignal(timeoutMs, signal)
+    })
+
+    status = res.status
+    const elapsed = Date.now() - startedAt
+
+    EventBus.emit({
+      type: EVENT_TYPES.MCP_REQUEST,
+      payload: { server: serverName, action, method, elapsed, status }
+    }).catch(() => {})
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "")
+      const reason = classifyHttpError(null, status)
+      throw new McpError(
+        `mcp server "${serverName}" HTTP ${status} on ${method} ${url}: ${text.slice(0, 500)}`,
+        { reason, server: serverName, action, phase: "request", statusCode: status }
+      )
+    }
+    return res.json().catch(() => ({}))
+  } catch (error) {
+    if (error instanceof McpError) throw error
+    const reason = classifyHttpError(error, status)
+    throw new McpError(
+      `mcp server "${serverName}" ${reason} on ${method} ${url}: ${error.message}`,
+      { reason, server: serverName, action, phase: "request", statusCode: status }
+    )
+  }
+}
+
+export function createHttpMcpClient(serverName, config) {
+  const baseUrl = String(config.url || "").replace(/\/$/, "")
+  const timeoutMs = Number(config.timeout_ms || 10000)
+  const headers = config.headers || {}
+
+  return {
+    serverName,
+    transport: "http",
+    async health() {
+      try {
+        await requestJson({ serverName, method: "GET", url: `${baseUrl}/health`, timeoutMs, headers })
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, error: error.message, reason: error.reason || "unknown" }
+      }
+    },
+    async listTools() {
+      const out = await requestJson({ serverName, method: "GET", url: `${baseUrl}/tools`, timeoutMs, headers })
+      return Array.isArray(out?.tools) ? out.tools : []
+    },
+    async listPrompts() {
+      try {
+        const out = await requestJson({ serverName, method: "GET", url: `${baseUrl}/prompts`, timeoutMs, headers })
+        return Array.isArray(out?.prompts) ? out.prompts : []
+      } catch {
+        return []
+      }
+    },
+    async getPrompt(name, args = {}) {
+      return requestJson({
+        serverName,
+        method: "POST",
+        url: `${baseUrl}/prompts/${encodeURIComponent(name)}`,
+        body: { arguments: args },
+        timeoutMs,
+        headers
+      })
+    },
+    async listResources() {
+      try {
+        const out = await requestJson({ serverName, method: "GET", url: `${baseUrl}/resources`, timeoutMs, headers })
+        return Array.isArray(out?.resources) ? out.resources : []
+      } catch (error) {
+        if (error.reason === "server_crash" || error.reason === "timeout") throw error
+        return []
+      }
+    },
+    async listTemplates() {
+      try {
+        const out = await requestJson({ serverName, method: "GET", url: `${baseUrl}/templates`, timeoutMs, headers })
+        return Array.isArray(out?.templates) ? out.templates : []
+      } catch {
+        return []
+      }
+    },
+    async callTool(name, args = {}, signal = null) {
+      const result = await requestJson({
+        serverName,
+        method: "POST",
+        url: `${baseUrl}/tools/${encodeURIComponent(name)}`,
+        body: { args },
+        timeoutMs,
+        headers,
+        signal
+      })
+      return normalizeToolResult(result, serverName, name)
+    },
+    shutdown() {
+      // HTTP client is stateless — no persistent connections to clean up
+    }
+  }
+}