@kkelly-offical/kkcode 0.1.2

package/src/skill/builtin/tdd.mjs

@@ -0,0 +1,54 @@
+export const name = "tdd"
+export const description = "Start TDD workflow: scaffold → test → implement → refactor (usage: /tdd <feature description>)"
+
+export async function run(ctx) {
+  const feature = (ctx.args || "").trim()
+
+  if (!feature) {
+    return `Please describe the feature to develop with TDD.
+
+Usage: /tdd <feature description>
+
+Examples:
+  /tdd add a user registration endpoint with email validation
+  /tdd implement a caching layer for API responses
+  /tdd create a file upload component with drag-and-drop`
+  }
+
+  return `Execute Test-Driven Development for the following feature:
+
+**Feature**: ${feature}
+
+Follow this strict TDD cycle:
+
+## Step 1: SCAFFOLD — Define interfaces
+- Analyze the feature requirements
+- Identify the public API: function signatures, types, interfaces
+- Create empty implementation files with stub exports
+- Verify the project compiles with stubs
+
+## Step 2: RED — Write failing tests FIRST
+- Write tests that exercise the expected behavior
+- Cover: happy path, edge cases, error conditions, boundary values
+- Run tests to confirm they FAIL (this is critical — you must see red)
+- Use the project's existing test framework (detect from package.json, pyproject.toml, go.mod, etc.)
+
+## Step 3: GREEN — Minimum code to pass
+- Implement the SIMPLEST code that makes ALL tests pass
+- Do NOT optimize or add features beyond what tests require
+- Run tests after each implementation step
+
+## Step 4: REFACTOR — Improve while green
+- Extract helpers, improve naming, reduce duplication
+- Run tests AFTER EVERY refactoring step — they must stay green
+- If a test breaks, undo the last change
+
+## Coverage Target: 80%+
+Run coverage after completion: \`npx jest --coverage\`, \`pytest --cov\`, \`go test -cover\`, etc.
+
+## Report after each cycle:
+1. Tests written (count and names)
+2. Tests passing/failing
+3. Coverage percentage
+4. Decisions made during implementation`
+}

package/src/skill/generator.mjs

@@ -0,0 +1,113 @@
+import { writeFile, mkdir } from "node:fs/promises"
+import { join, basename } from "node:path"
+import { homedir } from "node:os"
+import { requestProvider } from "../provider/router.mjs"
+
+const SKILL_GEN_SYSTEM = `You are a skill generator for kkcode, a terminal AI coding agent.
+Your task is to generate a skill file based on the user's description.
+
+A skill is a reusable slash command. You can generate two types:
+
+## Type 1: Markdown Template (.md)
+Simple prompt templates with variable expansion.
+Variables: $ARGUMENTS, $CWD, $MODE, $PROJECT, $1, $2, ...
+
+Example:
+\`\`\`markdown
+Review the code changes in $CWD and provide feedback.
+Focus on: $ARGUMENTS
+Project: $PROJECT
+\`\`\`
+
+## Type 2: Programmable Skill (.mjs)
+JavaScript module with full control. Must export: name, description, run(ctx).
+ctx has: { args, cwd, mode, model, provider }
+
+Example:
+\`\`\`javascript
+export const name = "test-coverage"
+export const description = "Run tests and analyze coverage"
+
+export async function run({ args, cwd }) {
+  return \`Run the test suite in \${cwd} and analyze code coverage.
+Focus on: \${args || "all files"}
+Report uncovered lines and suggest tests to add.\`
+}
+\`\`\`
+
+## Rules
+- Choose .md for simple prompt templates, .mjs for anything needing logic
+- The skill name should be kebab-case
+- Keep the generated prompt focused and actionable
+- Output ONLY the file content, no explanation
+- First line must be a comment with the skill name: <!-- skill: name --> for .md, or // skill: name for .mjs`
+
+/**
+ * Generate a skill file from a natural language description.
+ * Returns { name, filename, content, type } or null on failure.
+ */
+export async function generateSkill({ description, configState, providerType, model, baseUrl, apiKeyEnv }) {
+  const response = await requestProvider({
+    configState,
+    providerType,
+    model,
+    system: SKILL_GEN_SYSTEM,
+    messages: [{ role: "user", content: `Create a skill for: ${description}` }],
+    tools: [],
+    baseUrl,
+    apiKeyEnv
+  })
+
+  const text = (response.text || "").trim()
+  if (!text) return null
+
+  // Detect type from content
+  const isMjs = text.includes("export ") || text.includes("export const") || text.includes("export async")
+  const type = isMjs ? "mjs" : "md"
+
+  // Extract skill name from first line comment
+  let name = null
+  const nameMatch = text.match(/(?:<!--\s*skill:\s*|\/\/\s*skill:\s*)([a-z0-9-]+)/i)
+  if (nameMatch) name = nameMatch[1].toLowerCase()
+
+  // Fallback: derive name from description
+  if (!name) {
+    name = description
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, "")
+      .trim()
+      .replace(/\s+/g, "-")
+      .slice(0, 40)
+    if (!name) name = `skill-${Date.now()}`
+  }
+
+  // Strip markdown code fences if present
+  let content = text
+  const fenceMatch = content.match(/```(?:markdown|javascript|js|mjs)?\n([\s\S]*?)\n```/)
+  if (fenceMatch) content = fenceMatch[1]
+
+  const filename = `${name}.${type}`
+  return { name, filename, content, type }
+}
+
+/**
+ * Save a skill to the global skills directory.
+ */
+export async function saveSkillGlobal(filename, content) {
+  const dir = join(homedir(), ".kkcode", "skills")
+  await mkdir(dir, { recursive: true })
+  const filePath = join(dir, filename)
+  await writeFile(filePath, content, "utf-8")
+  return filePath
+}
+
+/**
+ * Save a skill to the project skills directory.
+ */
+export async function saveSkillProject(filename, content, cwd = process.cwd()) {
+  const dir = join(cwd, ".kkcode", "skills")
+  await mkdir(dir, { recursive: true })
+  const filePath = join(dir, filename)
+  await writeFile(filePath, content, "utf-8")
+  return filePath
+}

package/src/skill/registry.mjs

@@ -0,0 +1,336 @@
+import path from "node:path"
+import { access, readdir, readFile } from "node:fs/promises"
+import { pathToFileURL, fileURLToPath } from "node:url"
+import { exec } from "node:child_process"
+import { promisify } from "node:util"
+import { parse as parseYaml } from "yaml"
+import { McpRegistry } from "../mcp/registry.mjs"
+import { loadCustomCommands, applyCommandTemplate } from "../command/custom-commands.mjs"
+
+const execAsync = promisify(exec)
+
+async function exists(target) {
+  try {
+    await access(target)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ * Returns { meta: {}, body: string }
+ */
+function parseFrontmatter(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/)
+  if (!match) return { meta: {}, body: raw.trim() }
+  try {
+    return { meta: parseYaml(match[1]) || {}, body: match[2].trim() }
+  } catch {
+    return { meta: {}, body: raw.trim() }
+  }
+}
+
+/**
+ * Replace !`command` patterns with command stdout.
+ */
+async function injectDynamicContext(template, cwd) {
+  const pattern = /!\`([^`]+)\`/g
+  const matches = [...template.matchAll(pattern)]
+  if (!matches.length) return template
+  let result = template
+  for (const m of matches) {
+    try {
+      const { stdout } = await execAsync(m[1], { cwd, timeout: 10000 })
+      result = result.replace(m[0], stdout.trim())
+    } catch {
+      result = result.replace(m[0], `[command failed: ${m[1]}]`)
+    }
+  }
+  return result
+}
+
+/**
+ * Load SKILL.md directory-format skills from a directory.
+ * Scans for <dir>/<name>/SKILL.md
+ */
+async function loadAuxFiles(skillDir) {
+  const aux = {}
+  try {
+    const entries = await readdir(skillDir, { withFileTypes: true })
+    for (const e of entries) {
+      if (!e.isFile() || e.name === "SKILL.md") continue
+      aux[e.name] = path.join(skillDir, e.name)
+    }
+  } catch { /* ignore */ }
+  return aux
+}
+
+async function loadSkillDirs(dir, scope) {
+  if (!(await exists(dir))) return []
+  const entries = await readdir(dir, { withFileTypes: true })
+  const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort()
+  const skills = []
+  for (const name of dirs) {
+    const skillDir = path.join(dir, name)
+    const mdPath = path.join(skillDir, "SKILL.md")
+    if (!(await exists(mdPath))) continue
+    try {
+      const raw = await readFile(mdPath, "utf8")
+      const { meta, body } = parseFrontmatter(raw)
+      const auxFiles = await loadAuxFiles(skillDir)
+      skills.push({
+        name: meta.name || name,
+        description: meta.description || name,
+        type: "skill_md",
+        scope,
+        source: mdPath,
+        skillDir,
+        template: body,
+        auxFiles,
+        disableModelInvocation: !!meta["disable-model-invocation"],
+        userInvocable: meta["user-invocable"] !== false,
+        allowedTools: meta["allowed-tools"] || null,
+        model: meta.model || null,
+        contextFork: !!meta["context-fork"]
+      })
+    } catch { /* skip broken */ }
+  }
+  return skills
+}
+
+/**
+ * Load .mjs programmable skills from a directory.
+ * Each .mjs file should export: { name, description, run(ctx) }
+ * run() returns a string prompt to send to the model.
+ */
+async function loadMjsSkills(dir, scope) {
+  if (!(await exists(dir))) return []
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files = entries
+    .filter((e) => e.isFile() && e.name.endsWith(".mjs"))
+    .map((e) => e.name)
+    .sort()
+
+  const skills = []
+  for (const file of files) {
+    const full = path.join(dir, file)
+    try {
+      const mod = await import(pathToFileURL(full).href)
+      const name = mod.name || path.basename(file, ".mjs")
+      skills.push({
+        name,
+        description: mod.description || name,
+        type: "mjs",
+        scope,
+        source: full,
+        run: typeof mod.run === "function" ? mod.run : null
+      })
+    } catch {
+      // Skip broken skill files silently
+    }
+  }
+  return skills
+}
+
+/**
+ * Convert custom commands (.md templates) to skill format.
+ */
+function customCommandsToSkills(commands) {
+  return commands.map((cmd) => ({
+    name: cmd.name,
+    description: `custom command (${cmd.scope})`,
+    type: "template",
+    scope: cmd.scope,
+    source: cmd.source,
+    template: cmd.template
+  }))
+}
+
+/**
+ * Convert MCP prompts to skill format.
+ */
+function mcpPromptsToSkills(prompts) {
+  return prompts.map((p) => ({
+    name: p.name,
+    description: p.description || `${p.server}:${p.name}`,
+    type: "mcp_prompt",
+    scope: "mcp",
+    server: p.server,
+    promptId: p.id,
+    arguments: p.arguments || []
+  }))
+}
+
+const state = {
+  skills: new Map(),
+  loaded: false
+}
+
+export const SkillRegistry = {
+  /**
+   * Load all skills from all sources.
+   */
+  async initialize(config, cwd = process.cwd()) {
+    state.skills.clear()
+
+    // Source 0: Built-in skills (shipped with kkcode)
+    const builtinDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "builtin")
+    const builtinSkills = await loadMjsSkills(builtinDir, "builtin")
+    for (const skill of builtinSkills) {
+      state.skills.set(skill.name, skill)
+    }
+
+    // Source 1: Custom commands (.md templates)
+    const customCommands = await loadCustomCommands(cwd)
+    for (const skill of customCommandsToSkills(customCommands)) {
+      state.skills.set(skill.name, skill)
+    }
+
+    // Source 2: Programmable skills (.mjs)
+    const userRoot = process.env.USERPROFILE || process.env.HOME || cwd
+    const globalSkillDir = path.join(userRoot, ".kkcode", "skills")
+    const projectSkillDir = path.join(cwd, ".kkcode", "skills")
+    const [globalSkills, projectSkills, globalSkillMds, projectSkillMds] = await Promise.all([
+      loadMjsSkills(globalSkillDir, "global"),
+      loadMjsSkills(projectSkillDir, "project"),
+      loadSkillDirs(globalSkillDir, "global"),
+      loadSkillDirs(projectSkillDir, "project")
+    ])
+    // Project skills override global skills with same name
+    for (const skill of [...globalSkills, ...projectSkills, ...globalSkillMds, ...projectSkillMds]) {
+      state.skills.set(skill.name, skill)
+    }
+
+    // Source 3: MCP prompts (if MCP is initialized)
+    if (McpRegistry.isReady()) {
+      const prompts = McpRegistry.listPrompts()
+      for (const skill of mcpPromptsToSkills(prompts)) {
+        // Prefix MCP skills to avoid name collisions
+        const key = `mcp:${skill.name}`
+        state.skills.set(key, { ...skill, name: key })
+      }
+    }
+
+    state.loaded = true
+  },
+
+  isReady() {
+    return state.loaded
+  },
+
+  list() {
+    return [...state.skills.values()]
+  },
+
+  get(name) {
+    return state.skills.get(name) || null
+  },
+
+  /**
+   * Execute a skill and return the expanded prompt string.
+   */
+  async execute(name, args = "", context = {}) {
+    const skill = state.skills.get(name)
+    if (!skill) return null
+
+    if (skill.type === "mjs" && skill.run) {
+      // Programmable skill — call run() to get prompt
+      try {
+        const result = await skill.run({
+          args,
+          cwd: context.cwd || process.cwd(),
+          mode: context.mode || "agent",
+          model: context.model || "",
+          provider: context.provider || ""
+        })
+        return result == null ? "" : typeof result === "string" ? result : JSON.stringify(result)
+      } catch (error) {
+        return `skill execution error (${name}): ${error?.message || String(error)}`
+      }
+    }
+
+    if (skill.type === "template" && skill.template) {
+      // Template skill — expand $ARGUMENTS, $1, $2, etc.
+      return applyCommandTemplate(skill.template, args, {
+        path: context.cwd || process.cwd(),
+        mode: context.mode || "agent",
+        provider: context.provider || "",
+        cwd: context.cwd || process.cwd(),
+        project: path.basename(context.cwd || process.cwd())
+      })
+    }
+
+    if (skill.type === "skill_md" && skill.template) {
+      const cwd = context.cwd || process.cwd()
+      let prompt = applyCommandTemplate(skill.template, args, {
+        path: cwd, mode: context.mode || "agent",
+        provider: context.provider || "", cwd, project: path.basename(cwd)
+      })
+      // Resolve $FILE{name} references to auxiliary file contents
+      if (skill.auxFiles) {
+        const filePattern = /\$FILE\{([^}]+)\}/g
+        const fileMatches = [...prompt.matchAll(filePattern)]
+        for (const m of fileMatches) {
+          const filePath = skill.auxFiles[m[1]]
+          if (filePath) {
+            try {
+              const content = await readFile(filePath, "utf8")
+              prompt = prompt.replace(m[0], content.trim())
+            } catch {
+              prompt = prompt.replace(m[0], `[file not found: ${m[1]}]`)
+            }
+          }
+        }
+      }
+      prompt = await injectDynamicContext(prompt, cwd)
+      if (skill.contextFork) {
+        return { prompt, contextFork: true, model: skill.model }
+      }
+      return prompt
+    }
+
+    if (skill.type === "mcp_prompt" && skill.promptId) {
+      // MCP prompt — fetch from server
+      const promptArgs = {}
+      if (args) {
+        // Simple: pass entire args string as first argument
+        const argDefs = skill.arguments || []
+        if (argDefs.length === 1) {
+          promptArgs[argDefs[0].name] = args
+        } else if (argDefs.length > 1) {
+          // Split args by spaces for multiple arguments
+          const tokens = args.split(/\s+/)
+          for (let i = 0; i < argDefs.length && i < tokens.length; i++) {
+            promptArgs[argDefs[i].name] = tokens[i]
+          }
+        }
+      }
+      const result = await McpRegistry.getPrompt(skill.promptId, promptArgs)
+      // MCP prompt result: { messages: [{ role, content: { type, text } }] }
+      if (result?.messages) {
+        return result.messages
+          .map((m) => {
+            if (typeof m.content === "string") return m.content
+            if (m.content?.text) return m.content.text
+            return ""
+          })
+          .filter(Boolean)
+          .join("\n\n")
+      }
+      return JSON.stringify(result)
+    }
+
+    return null
+  },
+
+  /**
+   * Return skill metadata for system prompt inclusion.
+   */
+  listForSystemPrompt() {
+    return [...state.skills.values()]
+      .filter((s) => !s.disableModelInvocation)
+      .map((s) => ({ name: s.name, description: s.description }))
+  }
+}

package/src/storage/audit-store.mjs

@@ -0,0 +1,83 @@
+import { ensureUserRoot, auditStorePath } from "./paths.mjs"
+import { readJson, writeJson } from "./json-store.mjs"
+
+const state = {
+  maxEntries: 5000
+}
+
+function defaults() {
+  return {
+    updatedAt: Date.now(),
+    entries: []
+  }
+}
+
+export function configureAuditStore(options = {}) {
+  if (Number.isInteger(options.maxEntries) && options.maxEntries > 100) {
+    state.maxEntries = options.maxEntries
+  }
+}
+
+export async function readAuditStore() {
+  await ensureUserRoot()
+  return readJson(auditStorePath(), defaults())
+}
+
+export async function appendAuditEntry(entry) {
+  const store = await readAuditStore()
+  store.entries.push({
+    id: `aud_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    createdAt: Date.now(),
+    ...entry
+  })
+  if (store.entries.length > state.maxEntries) {
+    store.entries = store.entries.slice(-state.maxEntries)
+  }
+  store.updatedAt = Date.now()
+  await writeJson(auditStorePath(), store)
+  return store.entries[store.entries.length - 1]
+}
+
+export async function listAuditEntries(options = {}) {
+  const store = await readAuditStore()
+
+  const query = typeof options === "number" ? { limit: options } : options
+  const limit = Math.max(1, Number(query.limit || 200))
+  const sessionId = query.sessionId || null
+  const tool = query.tool || null
+  const type = query.type || null
+  const sinceMs = query.sinceMs || null
+
+  const list = store.entries.filter((entry) => {
+    if (sessionId && entry.sessionId !== sessionId) return false
+    if (tool && entry.tool !== tool) return false
+    if (type && entry.type !== type) return false
+    if (sinceMs && entry.createdAt < sinceMs) return false
+    return true
+  })
+
+  return list.slice(-limit).reverse()
+}
+
+export async function auditStats() {
+  const store = await readAuditStore()
+  const now = Date.now()
+  const oneHour = now - 60 * 60 * 1000
+  const oneDay = now - 24 * 60 * 60 * 1000
+
+  let error1h = 0
+  let error24h = 0
+  for (const entry of store.entries) {
+    const isError = String(entry.type || "").includes("error") || entry.ok === false
+    if (!isError) continue
+    if (entry.createdAt >= oneHour) error1h += 1
+    if (entry.createdAt >= oneDay) error24h += 1
+  }
+
+  return {
+    total: store.entries.length,
+    error1h,
+    error24h,
+    maxEntries: state.maxEntries
+  }
+}

package/src/storage/event-log.mjs

@@ -0,0 +1,82 @@
+import path from "node:path"
+import { appendFile, readdir, rename, stat, unlink } from "node:fs/promises"
+import { ensureUserRoot, eventLogPath, userRootDir } from "./paths.mjs"
+
+const state = {
+  rotateMb: 32,
+  retainDays: 14
+}
+
+function now() {
+  return Date.now()
+}
+
+function maxBytes() {
+  return Math.max(1, Number(state.rotateMb || 32)) * 1024 * 1024
+}
+
+export function configureEventLog(options = {}) {
+  if (Number.isFinite(options.rotateMb) && options.rotateMb > 0) state.rotateMb = Number(options.rotateMb)
+  if (Number.isFinite(options.retainDays) && options.retainDays > 0) state.retainDays = Number(options.retainDays)
+}
+
+async function maybeRotate() {
+  const file = eventLogPath()
+  const info = await stat(file).catch(() => null)
+  if (!info || info.size < maxBytes()) return
+  const rotated = path.join(userRootDir(), `events.${now()}.log`)
+  await rename(file, rotated).catch(() => {})
+}
+
+async function cleanupOldLogs() {
+  const cutoff = now() - Math.max(1, Number(state.retainDays || 14)) * 24 * 60 * 60 * 1000
+  const entries = await readdir(userRootDir(), { withFileTypes: true }).catch(() => [])
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    if (!entry.name.startsWith("events.") || !entry.name.endsWith(".log")) continue
+    const file = path.join(userRootDir(), entry.name)
+    const info = await stat(file).catch(() => null)
+    if (!info) continue
+    if (info.mtimeMs < cutoff) {
+      await unlink(file).catch(() => {})
+    }
+  }
+}
+
+export async function appendEventLog(event) {
+  await ensureUserRoot()
+  await maybeRotate()
+  await appendFile(eventLogPath(), JSON.stringify(event) + "\n", "utf8")
+  await cleanupOldLogs()
+}
+
+export async function eventLogStats() {
+  await ensureUserRoot()
+  const root = userRootDir()
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => [])
+  let activeBytes = 0
+  let rotatedBytes = 0
+  let rotatedFiles = 0
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    if (entry.name === "events.log") {
+      const info = await stat(path.join(root, entry.name)).catch(() => null)
+      if (info) activeBytes += info.size
+      continue
+    }
+    if (entry.name.startsWith("events.") && entry.name.endsWith(".log")) {
+      rotatedFiles += 1
+      const info = await stat(path.join(root, entry.name)).catch(() => null)
+      if (info) rotatedBytes += info.size
+    }
+  }
+
+  return {
+    rotateMb: state.rotateMb,
+    retainDays: state.retainDays,
+    activeBytes,
+    rotatedFiles,
+    rotatedBytes
+  }
+}