@kkelly-offical/kkcode 0.1.2 → 0.1.6

package/src/core/constants.mjs

@@ -1,46 +1,91 @@
-export const MODES = ["ask", "plan", "agent", "longagent"]
-
-export const TOOL_STATUSES = ["running", "completed", "error", "cancelled"]
-
-export const PERMISSION_DECISIONS = ["allow_once", "allow_session", "deny"]
-
-export const DEFAULT_MAX_STEPS = 8
-export const DEFAULT_REQUEST_TIMEOUT_MS = 120000
-export const DEFAULT_RETRY_ATTEMPTS = 3
-export const DEFAULT_LONGAGENT_RETRY_STORM_THRESHOLD = 3
-export const DEFAULT_LONGAGENT_TOKEN_ALERT_THRESHOLD = 120000
-
-export const EVENT_TYPES = {
-  TURN_START: "turn.start",
-  TURN_STEP_START: "turn.step.start",
-  TURN_STEP_FINISH: "turn.step.finish",
-  TURN_FINISH: "turn.finish",
-  TURN_ERROR: "turn.error",
-  TOOL_START: "tool.start",
-  TOOL_FINISH: "tool.finish",
-  TOOL_ERROR: "tool.error",
-  PERMISSION_ASKED: "permission.asked",
-  PERMISSION_DECIDED: "permission.decided",
-  REVIEW_DECISION: "review.decision",
-  MCP_HEALTH: "mcp.health",
-  MCP_REQUEST: "mcp.request",
-  LONGAGENT_HEARTBEAT: "longagent.heartbeat",
-  LONGAGENT_ALERT: "longagent.alert",
-  LONGAGENT_PHASE_CHANGED: "longagent.phase.changed",
-  LONGAGENT_GATE_CHECKED: "longagent.gate.checked",
-  LONGAGENT_RECOVERY_ENTERED: "longagent.recovery.entered",
-  LONGAGENT_INTAKE_STARTED: "longagent.intake.started",
-  LONGAGENT_PLAN_FROZEN: "longagent.plan.frozen",
-  LONGAGENT_STAGE_STARTED: "longagent.stage.started",
-  LONGAGENT_STAGE_TASK_DISPATCHED: "longagent.stage.task.dispatched",
-  LONGAGENT_STAGE_TASK_FINISHED: "longagent.stage.task.finished",
-  LONGAGENT_STAGE_FINISHED: "longagent.stage.finished",
-  LONGAGENT_SCAFFOLD_COMPLETE: "longagent.scaffold.complete",
-  LONGAGENT_GIT_BRANCH_CREATED: "longagent.git.branch.created",
-  LONGAGENT_GIT_STAGE_COMMITTED: "longagent.git.stage.committed",
-  LONGAGENT_GIT_MERGED: "longagent.git.merged",
-  SESSION_COMPACTED: "session.compacted",
-  TURN_USAGE_UPDATE: "turn.usage.update",
-  STREAM_TEXT_START: "stream.text.start",
-  STREAM_THINKING_START: "stream.thinking.start"
-}
+export const MODES = ["ask", "plan", "agent", "longagent"]
+
+export const TOOL_STATUSES = ["running", "completed", "error", "cancelled"]
+
+export const PERMISSION_DECISIONS = ["allow_once", "allow_session", "deny"]
+
+export const DEFAULT_MAX_STEPS = 8
+export const DEFAULT_REQUEST_TIMEOUT_MS = 120000
+export const DEFAULT_RETRY_ATTEMPTS = 3
+export const DEFAULT_LONGAGENT_RETRY_STORM_THRESHOLD = 3
+export const DEFAULT_LONGAGENT_TOKEN_ALERT_THRESHOLD = 120000
+
+export const LONGAGENT_4STAGE_STAGES = {
+  PREVIEW: "preview",
+  BLUEPRINT: "blueprint",
+  CODING: "coding",
+  DEBUGGING: "debugging"
+}
+
+export const EVENT_TYPES = {
+  TURN_START: "turn.start",
+  TURN_STEP_START: "turn.step.start",
+  TURN_STEP_FINISH: "turn.step.finish",
+  TURN_FINISH: "turn.finish",
+  TURN_ERROR: "turn.error",
+  TOOL_START: "tool.start",
+  TOOL_FINISH: "tool.finish",
+  TOOL_ERROR: "tool.error",
+  PERMISSION_ASKED: "permission.asked",
+  PERMISSION_DECIDED: "permission.decided",
+  REVIEW_DECISION: "review.decision",
+  MCP_HEALTH: "mcp.health",
+  MCP_REQUEST: "mcp.request",
+  MCP_RECONNECT: "mcp.reconnect",
+  MCP_CIRCUIT_OPEN: "mcp.circuit_open",
+  MCP_CIRCUIT_CLOSE: "mcp.circuit_close",
+  LONGAGENT_HEARTBEAT: "longagent.heartbeat",
+  LONGAGENT_ALERT: "longagent.alert",
+  LONGAGENT_PHASE_CHANGED: "longagent.phase.changed",
+  LONGAGENT_GATE_CHECKED: "longagent.gate.checked",
+  LONGAGENT_RECOVERY_ENTERED: "longagent.recovery.entered",
+  LONGAGENT_INTAKE_STARTED: "longagent.intake.started",
+  LONGAGENT_PLAN_FROZEN: "longagent.plan.frozen",
+  LONGAGENT_STAGE_STARTED: "longagent.stage.started",
+  LONGAGENT_STAGE_TASK_DISPATCHED: "longagent.stage.task.dispatched",
+  LONGAGENT_STAGE_TASK_FINISHED: "longagent.stage.task.finished",
+  LONGAGENT_STAGE_FINISHED: "longagent.stage.finished",
+  LONGAGENT_SCAFFOLD_COMPLETE: "longagent.scaffold.complete",
+  LONGAGENT_GIT_BRANCH_CREATED: "longagent.git.branch.created",
+  LONGAGENT_GIT_STAGE_COMMITTED: "longagent.git.stage.committed",
+  LONGAGENT_GIT_MERGED: "longagent.git.merged",
+  LONGAGENT_4STAGE_PREVIEW_START: "longagent.4stage.preview.start",
+  LONGAGENT_4STAGE_PREVIEW_COMPLETE: "longagent.4stage.preview.complete",
+  LONGAGENT_4STAGE_BLUEPRINT_START: "longagent.4stage.blueprint.start",
+  LONGAGENT_4STAGE_BLUEPRINT_COMPLETE: "longagent.4stage.blueprint.complete",
+  LONGAGENT_4STAGE_CODING_START: "longagent.4stage.coding.start",
+  LONGAGENT_4STAGE_CODING_COMPLETE: "longagent.4stage.coding.complete",
+  LONGAGENT_4STAGE_DEBUGGING_START: "longagent.4stage.debugging.start",
+  LONGAGENT_4STAGE_DEBUGGING_COMPLETE: "longagent.4stage.debugging.complete",
+  LONGAGENT_4STAGE_RETURN_TO_CODING: "longagent.4stage.return_to_coding",
+  LONGAGENT_HYBRID_PREVIEW_START: "longagent.hybrid.preview.start",
+  LONGAGENT_HYBRID_PREVIEW_COMPLETE: "longagent.hybrid.preview.complete",
+  LONGAGENT_HYBRID_BLUEPRINT_START: "longagent.hybrid.blueprint.start",
+  LONGAGENT_HYBRID_BLUEPRINT_COMPLETE: "longagent.hybrid.blueprint.complete",
+  LONGAGENT_HYBRID_DEBUGGING_START: "longagent.hybrid.debugging.start",
+  LONGAGENT_HYBRID_DEBUGGING_COMPLETE: "longagent.hybrid.debugging.complete",
+  LONGAGENT_HYBRID_RETURN_TO_CODING: "longagent.hybrid.return_to_coding",
+  LONGAGENT_HYBRID_BLUEPRINT_REVIEW: "longagent.hybrid.blueprint.review",
+  LONGAGENT_HYBRID_BLUEPRINT_VALIDATED: "longagent.hybrid.blueprint.validated",
+  LONGAGENT_HYBRID_CROSS_REVIEW: "longagent.hybrid.cross_review",
+  LONGAGENT_HYBRID_INCREMENTAL_GATE: "longagent.hybrid.incremental_gate",
+  LONGAGENT_HYBRID_CONTEXT_COMPRESSED: "longagent.hybrid.context_compressed",
+  LONGAGENT_HYBRID_BUDGET_WARNING: "longagent.hybrid.budget_warning",
+  LONGAGENT_HYBRID_CHECKPOINT_RESUMED: "longagent.hybrid.checkpoint_resumed",
+  LONGAGENT_HYBRID_REPLAN: "longagent.hybrid.replan",
+  LONGAGENT_HYBRID_MEMORY_LOADED: "longagent.hybrid.memory_loaded",
+  LONGAGENT_HYBRID_MEMORY_SAVED: "longagent.hybrid.memory_saved",
+  SESSION_COMPACTED: "session.compacted",
+  TURN_USAGE_UPDATE: "turn.usage.update",
+  STREAM_TEXT_START: "stream.text.start",
+  STREAM_THINKING_START: "stream.thinking.start",
+  LONGAGENT_DEGRADATION_APPLIED: "longagent.degradation.applied",
+  LONGAGENT_WRITE_LOOP_DETECTED: "longagent.write_loop.detected",
+  LONGAGENT_SEMANTIC_ERROR_REPEATED: "longagent.semantic_error.repeated",
+  LONGAGENT_PHASE_TIMEOUT: "longagent.phase.timeout",
+  LONGAGENT_GIT_CONFLICT_RESOLUTION: "longagent.git.conflict_resolution",
+  LONGAGENT_CHECKPOINT_CLEANED: "longagent.checkpoint.cleaned",
+  LONGAGENT_HYBRID_CHECKPOINT_INVALID: "longagent.hybrid.checkpoint_invalid",
+  LONGAGENT_STAGE_TASK_SKIPPED: "longagent.stage.task.skipped",
+  PROVIDER_FALLBACK: "provider.fallback"
+}

package/src/index.mjs

@@ -54,7 +54,7 @@ async function main() {
   }
 
   const program = new Command()
-  program.name("kkcode").description("kkcode CLI").version("0.1.2")
+  program.name("kkcode").description("kkcode CLI").version("0.1.6")
   program.addCommand(createChatCommand())
   program.addCommand(createThemeCommand())
   program.addCommand(createUsageCommand())

package/src/knowledge/frontend-aesthetics.txt

@@ -0,0 +1,39 @@
+<frontend_aesthetics>
+## Frontend Design Quality Rules
+
+When building frontend UI, avoid generic "AI-generated" aesthetics. Make creative, distinctive choices.
+
+### Typography
+- Avoid default fonts (Inter, Roboto, Arial, system-ui). Choose distinctive fonts.
+- Use high contrast: pair display fonts with monospace, serif with geometric sans.
+- Use extreme weight differences (200 vs 800) and 3x+ size jumps.
+- Load fonts from Google Fonts via <link> or @import.
+
+### Color
+- Define ALL colors as CSS variables in :root.
+- Use a dominant color with 1-2 sharp accents. Avoid evenly-distributed palettes.
+- Draw from real palettes: IDE themes (Nord, Catppuccin, Dracula), nature, cultural aesthetics.
+- AVOID: purple gradients on white, generic blue buttons, gray-on-gray cards.
+
+### Motion
+- One high-impact animation per page (staggered reveal on load).
+- Micro-interactions: hover lift, focus glow, press feedback.
+- Use CSS transitions/animations. Use animation-delay for staggered effects.
+
+### Layout
+- CSS Grid for page structure, Flexbox for components.
+- Generous whitespace. Consistent spacing scale (4/8/12/16/24/32/48/64px).
+- Mobile-first responsive design.
+
+### Depth & Atmosphere
+- Layered gradients, subtle patterns, backdrop-filter for glass effects.
+- Elevation hierarchy via box-shadow (not just border).
+- Noise/grain textures for premium feel.
+
+### What NOT to do
+- Cookie-cutter card grids with identical rounded corners
+- Generic hero with centered text + gradient
+- border-radius: 9999px on everything
+- Gray placeholder text that looks like wireframe
+- No visual rhythm (identical spacing everywhere)
+</frontend_aesthetics>

package/src/knowledge/loader.mjs

@@ -58,7 +58,8 @@ const LANGUAGE_MAP = {
 // Project type → scenario knowledge
 const TYPE_MAP = {
   backend: ["api-design.txt"],
-  fullstack: ["api-design.txt"],
+  fullstack: ["api-design.txt", "frontend-aesthetics.txt"],
+  frontend: ["frontend-aesthetics.txt"],
 }
 
 // Feature → knowledge file

package/src/knowledge/tailwind.txt

@@ -4,7 +4,16 @@ Tailwind CSS conventions:
 - 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
+- Colors: bg-blue-500, text-gray-900, use project's color palette from tailwind.config
 - Layout: flex, grid, container mx-auto, gap utilities
-- Customization: tailwind.config.js for theme extension
-- Avoid: inline styles, arbitrary values when a utility exists
+- Customization: tailwind.config.js for theme extension (colors, fonts, spacing)
+- Avoid: inline styles, arbitrary values when a utility exists
+
+Design quality with Tailwind:
+- READ tailwind.config.js first — use the project's defined colors/fonts/spacing
+- Prefer semantic color names (primary, accent, muted) over raw colors (blue-500)
+- Use ring utilities for focus states (ring-2 ring-offset-2)
+- Transition utilities: transition-all duration-200 ease-in-out for interactions
+- Shadow scale: shadow-sm → shadow → shadow-md → shadow-lg for elevation
+- Use group and group-hover for parent-child hover effects
+- Animate: animate-pulse for loading, animate-spin for spinners

package/src/mcp/client-http.mjs

@@ -1,157 +1,141 @@
-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
-    }
-  }
-}
+import { McpError } from "../core/errors.mjs"
+import { EventBus } from "../core/events.mjs"
+import { EVENT_TYPES } from "../core/constants.mjs"
+import { normalizeToolResult } from "./tool-result.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"
+}
+
+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((parseErr) => {
+      const action = body?.args ? "call_tool" : "request"
+      EventBus.emit({
+        type: EVENT_TYPES.MCP_REQUEST,
+        payload: { server: serverName, action, warning: "malformed_json_response", detail: parseErr.message }
+      }).catch(() => {})
+      return {}
+    })
+  } 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 {
+        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
+    }
+  }
+}