@kkelly-offical/kkcode 0.1.2

package/src/commands/background.mjs

@@ -0,0 +1,86 @@
+import { Command } from "commander"
+import { BackgroundManager } from "../orchestration/background-manager.mjs"
+import { buildContext, printContextWarnings } from "../context.mjs"
+
+async function withContext(action) {
+  const ctx = await buildContext()
+  printContextWarnings(ctx)
+  await BackgroundManager.tick(ctx.configState.config)
+  return action(ctx)
+}
+
+export function createBackgroundCommand() {
+  const cmd = new Command("background").description("inspect background delegated tasks")
+
+  cmd
+    .command("list")
+    .description("list background tasks")
+    .action(async () => {
+      await withContext(async () => {
+        const list = await BackgroundManager.list()
+        console.log(JSON.stringify(list, null, 2))
+      })
+    })
+
+  cmd
+    .command("show")
+    .description("show one background task")
+    .requiredOption("--id <id>", "task id")
+    .action(async (options) => {
+      await withContext(async () => {
+        const task = await BackgroundManager.get(options.id)
+        if (!task) {
+          console.error(`not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        console.log(JSON.stringify(task, null, 2))
+      })
+    })
+
+  cmd
+    .command("cancel")
+    .description("cancel one background task")
+    .requiredOption("--id <id>", "task id")
+    .action(async (options) => {
+      await withContext(async () => {
+        const ok = await BackgroundManager.cancel(options.id)
+        if (!ok) {
+          console.error(`not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        console.log(`cancel requested: ${options.id}`)
+      })
+    })
+
+  cmd
+    .command("retry")
+    .description("retry one interrupted/error background task")
+    .requiredOption("--id <id>", "task id")
+    .action(async (options) => {
+      await withContext(async (ctx) => {
+        const task = await BackgroundManager.retry(options.id, ctx.configState.config)
+        if (!task) {
+          console.error(`task not retryable or not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        console.log(`retry queued: ${task.id} (attempt=${task.attempt})`)
+      })
+    })
+
+  cmd
+    .command("clean")
+    .description("remove old completed/cancelled/error/interrupted tasks")
+    .option("--max-age <days>", "max age in days", "7")
+    .action(async (options) => {
+      await withContext(async () => {
+        const maxAge = Number(options.maxAge || 7) * 24 * 60 * 60 * 1000
+        const removed = await BackgroundManager.clean({ maxAge })
+        console.log(`removed ${removed.length} task(s)`)
+      })
+    })
+
+  return cmd
+}

package/src/commands/chat.mjs

@@ -0,0 +1,114 @@
+import { Command } from "commander"
+import { buildContext, printContextWarnings } from "../context.mjs"
+import { executeTurn, newSessionId, resolveMode } from "../session/engine.mjs"
+import { renderStatusBar } from "../theme/status-bar.mjs"
+import { applyCommandTemplate, loadCustomCommands } from "../command/custom-commands.mjs"
+import { ToolRegistry } from "../tool/registry.mjs"
+import { HookBus, initHookBus } from "../plugin/hook-bus.mjs"
+import { listProviders } from "../provider/router.mjs"
+
+export function createChatCommand() {
+  const providers = listProviders()
+  return new Command("chat")
+    .description("run one prompt in ask/plan/agent/longagent mode")
+    .argument("<prompt...>", "prompt text")
+    .option("--mode <mode>", "ask|plan|agent|longagent", "agent")
+    .option("--model <model>", "model id")
+    .option("--provider-type <type>", `provider type (${providers.join("|")})`)
+    .option("--base-url <url>", "provider base url override")
+    .option("--api-key-env <name>", "api key env override")
+    .option("--max-iterations <n>", "longagent max iterations (0 = unlimited)")
+    .option("--session <id>", "session id")
+    .action(async (promptParts, options) => {
+      const ctx = await buildContext()
+      printContextWarnings(ctx)
+      let prompt = promptParts.join(" ").trim()
+      if (prompt.startsWith("/")) {
+        const commands = await loadCustomCommands(process.cwd())
+        const [name, ...argTokens] = prompt.slice(1).split(/\s+/)
+        const custom = commands.find((item) => item.name === name)
+        if (custom) {
+          const args = argTokens.join(" ").trim()
+          prompt = applyCommandTemplate(custom.template, args, {
+            path: process.cwd()
+          })
+        }
+      }
+
+      const mode = resolveMode(options.mode)
+      const providerType = options.providerType ?? ctx.configState.config.provider.default
+      const providerDefaults = ctx.configState.config.provider[providerType]
+      if (!providerDefaults) {
+        throw new Error(`unknown provider type: ${providerType}`)
+      }
+      const model = options.model ?? providerDefaults.default_model
+      const sessionId = options.session || newSessionId()
+
+      await ToolRegistry.initialize({
+        config: ctx.configState.config,
+        cwd: process.cwd()
+      })
+
+      await initHookBus()
+      const chatParams = await HookBus.chatParams({
+        prompt,
+        mode,
+        model,
+        providerType,
+        sessionId,
+        baseUrl: options.baseUrl ?? null,
+        apiKeyEnv: options.apiKeyEnv ?? null
+      })
+
+      const result = await executeTurn({
+        prompt: chatParams.prompt ?? prompt,
+        mode: chatParams.mode ?? mode,
+        model: chatParams.model ?? model,
+        sessionId,
+        configState: ctx.configState,
+        providerType: chatParams.providerType ?? providerType,
+        baseUrl: chatParams.baseUrl ?? options.baseUrl ?? null,
+        apiKeyEnv: chatParams.apiKeyEnv ?? options.apiKeyEnv ?? null,
+        maxIterations: options.maxIterations !== undefined ? Number(options.maxIterations) : null,
+        output: ctx.configState.config.provider[chatParams.providerType ?? providerType]?.stream !== false
+          ? { write: (chunk) => process.stdout.write(String(chunk || "")) }
+          : null
+      })
+
+      const status = renderStatusBar({
+        mode,
+        model: result.model,
+        permission: ctx.configState.config.permission.default_policy,
+        tokenMeter: result.tokenMeter,
+        aggregation: ctx.configState.config.usage.aggregation,
+        cost: result.cost,
+        showCost: ctx.configState.config.ui.status.show_cost,
+        showTokenMeter: ctx.configState.config.ui.status.show_token_meter,
+        theme: ctx.themeState.theme,
+        layout: ctx.configState.config.ui.layout,
+        longagentState: mode === "longagent" ? result.longagent : null
+      })
+
+      console.log(status)
+      console.log("")
+      const streamEnabled = ctx.configState.config.provider[chatParams.providerType ?? providerType]?.stream !== false
+      if (!streamEnabled || !result.emittedText) {
+        console.log(result.reply)
+      }
+      console.log("")
+      if (result.toolEvents.length) {
+        console.log(`tool events: ${result.toolEvents.length}`)
+      }
+      if (result.pricingWarnings.length) {
+        for (const warning of result.pricingWarnings) {
+          console.log(`pricing warning: ${warning}`)
+        }
+      }
+      if (result.budgetWarnings.length) {
+        for (const warning of result.budgetWarnings) {
+          console.log(`budget warning: ${warning}`)
+        }
+      }
+      console.log(`session: ${sessionId}`)
+    })
+}

package/src/commands/command.mjs

@@ -0,0 +1,41 @@
+import { Command } from "commander"
+import { applyCommandTemplate, loadCustomCommands } from "../command/custom-commands.mjs"
+
+export function createCommandCommand() {
+  const cmd = new Command("command").description("inspect custom slash commands")
+
+  cmd
+    .command("list")
+    .description("list discovered custom commands")
+    .action(async () => {
+      const list = await loadCustomCommands(process.cwd())
+      if (!list.length) {
+        console.log("no custom commands found")
+        return
+      }
+      for (const item of list) {
+        console.log(`/${item.name} (${item.scope}) -> ${item.source}`)
+      }
+    })
+
+  cmd
+    .command("preview")
+    .description("preview command template expansion")
+    .requiredOption("--name <name>", "command name")
+    .option("--args <text>", "arguments text", "")
+    .action(async (options) => {
+      const list = await loadCustomCommands(process.cwd())
+      const item = list.find((cmd) => cmd.name === options.name)
+      if (!item) {
+        console.error(`command not found: ${options.name}`)
+        process.exitCode = 1
+        return
+      }
+      const expanded = applyCommandTemplate(item.template, options.args, {
+        path: process.cwd()
+      })
+      console.log(expanded)
+    })
+
+  return cmd
+}

package/src/commands/config.mjs

@@ -0,0 +1,44 @@
+import path from "node:path"
+import { readFile, writeFile } from "node:fs/promises"
+import { Command } from "commander"
+import YAML from "yaml"
+import { importConfig } from "../config/import-config.mjs"
+import { validateConfig } from "../config/schema.mjs"
+
+function parseInput(file, raw) {
+  if (file.endsWith(".json")) return JSON.parse(raw)
+  return YAML.parse(raw)
+}
+
+function stringifyOutput(file, data) {
+  if (file.endsWith(".json")) return JSON.stringify(data, null, 2) + "\n"
+  return YAML.stringify(data)
+}
+
+export function createConfigCommand() {
+  const cmd = new Command("config").description("manage kkcode config")
+
+  cmd
+    .command("import")
+    .description("import external config into kkcode format")
+    .requiredOption("--from <file>", "source config file path")
+    .option("--to <file>", "output file path", "kkcode.config.yaml")
+    .action(async (options) => {
+      const from = path.resolve(options.from)
+      const to = path.resolve(options.to)
+      const raw = await readFile(from, "utf8")
+      const parsed = parseInput(from, raw)
+      const imported = importConfig(parsed)
+      const check = validateConfig(imported)
+      if (!check.valid) {
+        console.error("import produced invalid config:")
+        for (const error of check.errors) console.error(`- ${error}`)
+        process.exitCode = 1
+        return
+      }
+      await writeFile(to, stringifyOutput(to, imported), "utf8")
+      console.log(`imported config written: ${to}`)
+    })
+
+  return cmd
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,148 @@
+import { Command } from "commander"
+import { exec as execCb } from "node:child_process"
+import { promisify } from "node:util"
+import { buildContext } from "../context.mjs"
+import { listProviders } from "../provider/router.mjs"
+import { eventLogStats } from "../storage/event-log.mjs"
+import { auditStats } from "../storage/audit-store.mjs"
+import { fsckSessionStore, flushNow } from "../session/store.mjs"
+import { BackgroundManager } from "../orchestration/background-manager.mjs"
+import { McpRegistry } from "../mcp/registry.mjs"
+
+const exec = promisify(execCb)
+
+async function hasCommand(cmd) {
+  const query = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`
+  try {
+    await exec(query)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function summarizeBackground(tasks) {
+  const counters = {
+    total: tasks.length,
+    pending: 0,
+    running: 0,
+    completed: 0,
+    error: 0,
+    cancelled: 0,
+    interrupted: 0
+  }
+  for (const task of tasks) {
+    if (counters[task.status] !== undefined) counters[task.status] += 1
+  }
+  return counters
+}
+
+async function buildDoctorReport() {
+  const ctx = await buildContext()
+  await flushNow()
+  await BackgroundManager.tick(ctx.configState.config)
+
+  const checks = {
+    node: true,
+    rg: await hasCommand("rg"),
+    git: await hasCommand("git")
+  }
+
+  const config = ctx.configState.config
+  const providers = []
+  for (const [name, provider] of Object.entries(config.provider || {})) {
+    if (name === "default") continue
+    if (!provider || typeof provider !== "object") continue
+    const keyEnv = provider.api_key_env || ""
+    providers.push({
+      name,
+      type: provider.type || name,
+      model: provider.default_model || null,
+      baseUrl: provider.base_url || null,
+      apiKeyEnv: keyEnv || null,
+      apiKeyConfigured: keyEnv ? Boolean(process.env[keyEnv]) : true
+    })
+  }
+
+  const events = await eventLogStats()
+  const audit = await auditStats()
+  const storage = await fsckSessionStore()
+  const backgroundTasks = await BackgroundManager.list()
+  await McpRegistry.initialize(config)
+  const mcpSnapshot = McpRegistry.healthSnapshot()
+  const mcpHealthy = mcpSnapshot.filter((item) => item.ok).length
+
+  return {
+    ok: storage.ok,
+    timestamp: new Date().toISOString(),
+    cwd: process.cwd(),
+    themeWarnings: ctx.themeState.errors,
+    config: {
+      defaultProvider: config.provider?.default || null,
+      userPath: ctx.configState.source.userPath,
+      projectPath: ctx.configState.source.projectPath,
+      warnings: ctx.configState.errors
+    },
+    runtime: {
+      providersRegistered: listProviders(),
+      providersConfigured: providers
+    },
+    checks,
+    mcp: {
+      configured: mcpSnapshot.length,
+      healthy: mcpHealthy,
+      unhealthy: mcpSnapshot.length - mcpHealthy,
+      servers: mcpSnapshot
+    },
+    storage: {
+      sessions: storage,
+      eventLog: events,
+      audit
+    },
+    background: summarizeBackground(backgroundTasks)
+  }
+}
+
+function printTextReport(report, themeWarnings = []) {
+  console.log("kkcode doctor")
+  console.log(`time: ${report.timestamp}`)
+  console.log(`cwd: ${report.cwd}`)
+  console.log(`default provider: ${report.config.defaultProvider}`)
+  console.log(`config.user: ${report.config.userPath || "(none)"}`)
+  console.log(`config.project: ${report.config.projectPath || "(none)"}`)
+  if (report.config.warnings.length) {
+    for (const warning of report.config.warnings) {
+      console.log(`config warning: ${warning}`)
+    }
+  }
+  for (const warning of themeWarnings) {
+    console.log(`theme warning: ${warning}`)
+  }
+  for (const p of report.runtime.providersConfigured) {
+    console.log(
+      `provider:${p.name} type=${p.type} model=${p.model || "?"} key=${p.apiKeyEnv || "-"} (${p.apiKeyConfigured ? "set" : "missing"})`
+    )
+  }
+  console.log(`check node=${report.checks.node ? "ok" : "missing"} rg=${report.checks.rg ? "ok" : "missing"} git=${report.checks.git ? "ok" : "missing"}`)
+  console.log(`mcp: configured=${report.mcp.configured} healthy=${report.mcp.healthy} unhealthy=${report.mcp.unhealthy}`)
+  console.log(`sessions: ok=${report.storage.sessions.ok} index=${report.storage.sessions.sessionsInIndex} files=${report.storage.sessions.filesOnDisk}`)
+  console.log(`events: active=${report.storage.eventLog.activeBytes} rotated=${report.storage.eventLog.rotatedFiles}`)
+  console.log(`audit: total=${report.storage.audit.total} error1h=${report.storage.audit.error1h} error24h=${report.storage.audit.error24h}`)
+  console.log(
+    `background: total=${report.background.total} running=${report.background.running} pending=${report.background.pending} interrupted=${report.background.interrupted} error=${report.background.error}`
+  )
+}
+
+export function createDoctorCommand() {
+  return new Command("doctor")
+    .description("run environment diagnostics")
+    .option("--json", "print structured diagnostics", false)
+    .action(async (options) => {
+      const report = await buildDoctorReport()
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2))
+        return
+      }
+      printTextReport(report, report.themeWarnings || [])
+    })
+}

package/src/commands/hook.mjs

@@ -0,0 +1,29 @@
+import { Command } from "commander"
+import { initHookBus, HookBus } from "../plugin/hook-bus.mjs"
+
+export function createHookCommand() {
+  const cmd = new Command("hook").description("inspect loaded hooks")
+
+  cmd
+    .command("list")
+    .description("list loaded hooks and loading errors")
+    .action(async () => {
+      await initHookBus(process.cwd())
+      const hooks = HookBus.list()
+      const errors = HookBus.errors()
+      console.log(`supported events: ${HookBus.supportedEvents().join(", ")}`)
+      if (!hooks.length) {
+        console.log("no hooks loaded")
+      } else {
+        for (const hook of hooks) {
+          console.log(`- ${hook.name} (${hook.source})`)
+        }
+      }
+      if (errors.length) {
+        console.log("hook loading errors:")
+        for (const err of errors) console.log(`- ${err}`)
+      }
+    })
+
+  return cmd
+}

package/src/commands/init.mjs

@@ -0,0 +1,141 @@
+import { join } from "node:path"
+import { mkdir, writeFile, access } from "node:fs/promises"
+import { createInterface } from "node:readline/promises"
+import { Command } from "commander"
+import YAML from "yaml"
+import { listProviders } from "../provider/router.mjs"
+import { validateConfig } from "../config/schema.mjs"
+
+async function exists(target) {
+  try { await access(target); return true } catch { return false }
+}
+
+async function askQuestion(rl, question, defaultValue = "") {
+  const suffix = defaultValue ? ` (${defaultValue})` : ""
+  const answer = await rl.question(`${question}${suffix}: `)
+  return answer.trim() || defaultValue
+}
+
+async function askChoice(rl, question, choices, defaultValue) {
+  const choiceStr = choices.map((c, i) => `${i + 1}. ${c}`).join("\n")
+  console.log(`\n${question}\n${choiceStr}`)
+  const answer = await rl.question(`choose [${defaultValue}]: `)
+  const trimmed = answer.trim()
+  if (!trimmed) return defaultValue
+  const idx = parseInt(trimmed, 10)
+  if (idx >= 1 && idx <= choices.length) return choices[idx - 1]
+  if (choices.includes(trimmed)) return trimmed
+  return defaultValue
+}
+
+const PROVIDER_DEFAULTS = {
+  openai: { api_key_env: "OPENAI_API_KEY", default_model: "gpt-5.3-codex" },
+  anthropic: { api_key_env: "ANTHROPIC_API_KEY", default_model: "claude-opus-4-6" },
+  ollama: { base_url: "http://localhost:11434", api_key_env: "", default_model: "llama3.1" },
+  "openai-compatible": { base_url: "", api_key_env: "", default_model: "" }
+}
+
+function buildConfig(answers) {
+  const config = {
+    provider: {
+      default: answers.provider
+    },
+    permission: {
+      default_policy: answers.permissionPolicy || "ask"
+    }
+  }
+  const block = {}
+  if (answers.baseUrl) block.base_url = answers.baseUrl
+  if (answers.apiKeyEnv) block.api_key_env = answers.apiKeyEnv
+  if (answers.model) block.default_model = answers.model
+  if (Object.keys(block).length) {
+    config.provider[answers.provider] = block
+  }
+  return config
+}
+
+async function runInteractive(rl) {
+  const providers = listProviders()
+  const provider = await askChoice(rl, "select default provider:", providers, "openai")
+  const defaults = PROVIDER_DEFAULTS[provider] || {}
+
+  let baseUrl = ""
+  let apiKeyEnv = ""
+  let model = ""
+
+  if (provider === "ollama") {
+    baseUrl = await askQuestion(rl, "ollama base URL", defaults.base_url)
+    model = await askQuestion(rl, "default model", defaults.default_model)
+  } else if (provider === "openai-compatible") {
+    baseUrl = await askQuestion(rl, "base URL", "")
+    apiKeyEnv = await askQuestion(rl, "API key env var", "")
+    model = await askQuestion(rl, "default model", "")
+  } else {
+    apiKeyEnv = await askQuestion(rl, "API key env var", defaults.api_key_env)
+    model = await askQuestion(rl, "default model", defaults.default_model)
+  }
+
+  const permissionPolicy = await askChoice(
+    rl,
+    "default permission policy:",
+    ["allow", "ask", "deny"],
+    "ask"
+  )
+
+  return { provider, baseUrl, apiKeyEnv, model, permissionPolicy }
+}
+
+export function createInitCommand() {
+  return new Command("init")
+    .description("initialize kkcode in current project")
+    .option("-y, --yes", "use defaults without prompting")
+    .action(async (options) => {
+      const cwd = process.cwd()
+      const configDir = join(cwd, ".kkcode")
+      const configFile = join(configDir, "config.yaml")
+
+      if (await exists(configFile)) {
+        console.log(`config already exists: ${configFile}`)
+        console.log("use 'kkcode config' to modify it")
+        return
+      }
+
+      let answers
+      if (options.yes) {
+        answers = {
+          provider: "openai",
+          baseUrl: "",
+          apiKeyEnv: "OPENAI_API_KEY",
+          model: "gpt-5.3-codex",
+          permissionPolicy: "ask"
+        }
+      } else {
+        const rl = createInterface({ input: process.stdin, output: process.stdout })
+        try {
+          answers = await runInteractive(rl)
+        } finally {
+          rl.close()
+        }
+      }
+
+      const config = buildConfig(answers)
+      const check = validateConfig(config)
+      if (!check.valid) {
+        console.error("generated config is invalid:")
+        for (const e of check.errors) console.error(`  - ${e}`)
+        process.exitCode = 1
+        return
+      }
+
+      await mkdir(configDir, { recursive: true })
+      await writeFile(configFile, YAML.stringify(config), "utf8")
+      console.log(`created: ${configFile}`)
+
+      const defaultProvider = config.provider.default
+      const providerCfg = config.provider[defaultProvider] || {}
+      if (providerCfg.api_key_env && !process.env[providerCfg.api_key_env]) {
+        console.log(`note: ${providerCfg.api_key_env} is not set in environment`)
+      }
+      console.log("run 'kkcode doctor' for full diagnostics")
+    })
+}