@kkelly-offical/kkcode 0.1.2

package/src/commands/session.mjs

@@ -0,0 +1,235 @@
+import path from "node:path"
+import { writeFile } from "node:fs/promises"
+import { Command } from "commander"
+import { exportSession, getSession, listSessions, forkSession, fsckSessionStore, gcSessionStore, flushNow } from "../session/store.mjs"
+import { newSessionId, executeTurn } from "../session/engine.mjs"
+import { listRecoverableSessions, getResumeContext, isRecoveryEnabled } from "../session/recovery.mjs"
+import { buildContext } from "../context.mjs"
+import { ToolRegistry } from "../tool/registry.mjs"
+
+function assertRecoveryEnabled(config, commandName) {
+  if (isRecoveryEnabled(config)) return true
+  console.error(`session recovery is disabled (session.recovery=false). command "${commandName}" is unavailable.`)
+  process.exitCode = 2
+  return false
+}
+
+export function createSessionCommand() {
+  const cmd = new Command("session").description("manage persisted kkcode sessions")
+
+  cmd
+    .command("fsck")
+    .description("check session index/data consistency")
+    .option("--json", "print as json", false)
+    .action(async (options) => {
+      const report = await fsckSessionStore()
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2))
+        return
+      }
+      console.log(`checked_at=${new Date(report.checkedAt).toLocaleString()}`)
+      console.log(`sessions_in_index=${report.sessionsInIndex} files_on_disk=${report.filesOnDisk}`)
+      console.log(`missing_data_files=${report.missingDataFiles.length}`)
+      console.log(`orphan_data_files=${report.orphanDataFiles.length}`)
+      console.log(`invalid_data_files=${report.invalidDataFiles.length}`)
+      for (const suggestion of report.suggestions) {
+        console.log(`suggestion: ${suggestion}`)
+      }
+      if (!report.ok) process.exitCode = 2
+    })
+
+  cmd
+    .command("gc")
+    .description("clean orphan/stale session data")
+    .option("--orphans-only", "only remove orphan session files", false)
+    .option("--max-age <days>", "remove stale sessions older than days", "30")
+    .option("--json", "print as json", false)
+    .action(async (options) => {
+      const result = await gcSessionStore({
+        orphansOnly: Boolean(options.orphansOnly),
+        maxAgeDays: Number(options.maxAge || 30)
+      })
+      await flushNow()
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2))
+        return
+      }
+      console.log(`removed orphan files: ${result.removed.orphanFiles.length}`)
+      console.log(`removed stale sessions: ${result.removed.staleSessions.length}`)
+      console.log(`removed checkpoint dirs: ${result.removed.checkpointDirs.length}`)
+      console.log(`total removed: ${result.totalRemoved}`)
+    })
+
+  cmd
+    .command("list")
+    .description("list sessions")
+    .option("--cwd-only", "filter by cwd", false)
+    .option("--roots", "only root sessions", false)
+    .option("--limit <n>", "max sessions", "30")
+    .action(async (options) => {
+      const list = await listSessions({
+        cwd: options.cwdOnly ? process.cwd() : null,
+        includeChildren: !options.roots,
+        limit: Number(options.limit || 30)
+      })
+      if (!list.length) {
+        console.log("no sessions found")
+        return
+      }
+      for (const session of list) {
+        const parent = session.parentSessionId ? ` parent=${session.parentSessionId}` : ""
+        console.log(
+          `${session.id}  ${session.mode}  ${session.providerType}  ${session.model}  ${new Date(session.updatedAt).toLocaleString()}${parent}`
+        )
+      }
+    })
+
+  cmd
+    .command("show")
+    .description("show one session")
+    .requiredOption("--id <id>", "session id")
+    .action(async (options) => {
+      const data = await getSession(options.id)
+      if (!data) {
+        console.error(`session not found: ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      console.log(JSON.stringify(data, null, 2))
+    })
+
+  cmd
+    .command("export")
+    .description("export session to json")
+    .requiredOption("--id <id>", "session id")
+    .option("--out <file>", "output file")
+    .action(async (options) => {
+      const data = await exportSession(options.id)
+      if (!data) {
+        console.error(`session not found: ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      const out = options.out ? path.resolve(options.out) : path.resolve(`session-${options.id}.json`)
+      await writeFile(out, JSON.stringify(data, null, 2) + "\n", "utf8")
+      console.log(`exported: ${out}`)
+    })
+
+  cmd
+    .command("fork")
+    .description("fork session into a new child session")
+    .requiredOption("--id <id>", "source session id")
+    .option("--new-id <id>", "new session id")
+    .option("--title <title>", "child title")
+    .action(async (options) => {
+      const newId = options.newId || newSessionId()
+      const out = await forkSession({
+        sessionId: options.id,
+        newSessionId: newId,
+        title: options.title || null
+      })
+      if (!out) {
+        console.error(`session not found: ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      console.log(`forked: ${newId} <- ${options.id}`)
+    })
+
+  cmd
+    .command("resume")
+    .description("resume a session from the last user message")
+    .requiredOption("--id <id>", "session id to resume")
+    .option("--mode <mode>", "override mode")
+    .option("--model <model>", "override model")
+    .action(async (options) => {
+      const ctx = await buildContext()
+      if (!assertRecoveryEnabled(ctx.configState.config, "session resume")) return
+
+      const resumeCtx = await getResumeContext(options.id, { enabled: true })
+      if (!resumeCtx) {
+        console.error(`session not found: ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      if (!resumeCtx.canResume) {
+        console.error(`no user message found in session ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      await ToolRegistry.initialize({ config: ctx.configState.config, cwd: process.cwd() })
+      const mode = options.mode || resumeCtx.session.mode
+      const model = options.model || resumeCtx.session.model
+      console.log(`resuming session ${options.id} (${resumeCtx.messageCount} messages)`)
+      console.log(`last prompt: ${resumeCtx.lastPrompt.slice(0, 100)}${resumeCtx.lastPrompt.length > 100 ? "..." : ""}`)
+      const result = await executeTurn({
+        prompt: resumeCtx.lastPrompt,
+        mode,
+        model,
+        sessionId: options.id,
+        configState: ctx.configState,
+        providerType: resumeCtx.session.providerType
+      })
+      console.log(result.reply)
+    })
+
+  cmd
+    .command("retry")
+    .description("retry the last failed turn in a session")
+    .requiredOption("--id <id>", "session id to retry")
+    .action(async (options) => {
+      const ctx = await buildContext()
+      if (!assertRecoveryEnabled(ctx.configState.config, "session retry")) return
+
+      const resumeCtx = await getResumeContext(options.id, { enabled: true })
+      if (!resumeCtx) {
+        console.error(`session not found: ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      if (!resumeCtx.canRetry) {
+        console.error(`session ${options.id} has no failed turn to retry`)
+        process.exitCode = 1
+        return
+      }
+      if (!resumeCtx.canResume) {
+        console.error(`no user message found in session ${options.id}`)
+        process.exitCode = 1
+        return
+      }
+      await ToolRegistry.initialize({ config: ctx.configState.config, cwd: process.cwd() })
+      console.log(`retrying failed turn in session ${options.id}`)
+      const result = await executeTurn({
+        prompt: resumeCtx.lastPrompt,
+        mode: resumeCtx.session.mode,
+        model: resumeCtx.session.model,
+        sessionId: options.id,
+        configState: ctx.configState,
+        providerType: resumeCtx.session.providerType
+      })
+      console.log(result.reply)
+    })
+
+  cmd
+    .command("recoverable")
+    .description("list sessions that can be resumed or retried")
+    .action(async () => {
+      const ctx = await buildContext()
+      if (!assertRecoveryEnabled(ctx.configState.config, "session recoverable")) return
+
+      const sessions = await listRecoverableSessions({
+        cwd: process.cwd(),
+        enabled: true
+      })
+      if (!sessions.length) {
+        console.log("no recoverable sessions")
+        return
+      }
+      for (const s of sessions) {
+        const reason = s.retryMeta?.inProgress ? "in-progress" : s.status === "error" ? "error" : "unknown"
+        console.log(`${s.id}  ${s.mode}  ${reason}  ${new Date(s.updatedAt).toLocaleString()}`)
+      }
+    })
+
+  return cmd
+}

package/src/commands/theme.mjs

@@ -0,0 +1,98 @@
+import path from "node:path"
+import { access, writeFile, readFile } from "node:fs/promises"
+import YAML from "yaml"
+import { Command } from "commander"
+import { DEFAULT_THEME } from "../theme/default-theme.mjs"
+import { validateTheme } from "../theme/schema.mjs"
+import { ensureProjectRoot, projectRootDir } from "../storage/paths.mjs"
+import { buildContext, printContextWarnings } from "../context.mjs"
+import { renderStatusBar } from "../theme/status-bar.mjs"
+
+async function fileExists(file) {
+  try {
+    await access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function parseTheme(file, raw) {
+  if (file.endsWith(".json")) return JSON.parse(raw)
+  return YAML.parse(raw)
+}
+
+export function createThemeCommand() {
+  const cmd = new Command("theme").description("manage kkcode theme files")
+
+  cmd
+    .command("init")
+    .description("create a neo-contrast theme template in the project")
+    .option("--path <file>", "output file path")
+    .option("--force", "overwrite existing file", false)
+    .action(async (options) => {
+      await ensureProjectRoot(process.cwd())
+      const target = options.path
+        ? path.resolve(options.path)
+        : path.join(projectRootDir(process.cwd()), "neo-contrast.theme.yaml")
+      if ((await fileExists(target)) && !options.force) {
+        console.error(`theme file exists: ${target} (use --force to overwrite)`)
+        process.exitCode = 1
+        return
+      }
+      await writeFile(target, YAML.stringify(DEFAULT_THEME), "utf8")
+      console.log(`theme template written: ${target}`)
+    })
+
+  cmd
+    .command("validate")
+    .description("validate a theme file")
+    .requiredOption("--file <file>", "theme file path")
+    .action(async (options) => {
+      const file = path.resolve(options.file)
+      const raw = await readFile(file, "utf8")
+      const parsed = parseTheme(file, raw)
+      const check = validateTheme(parsed)
+      if (!check.valid) {
+        console.error("theme is invalid:")
+        for (const error of check.errors) console.error(`- ${error}`)
+        process.exitCode = 1
+        return
+      }
+      console.log("theme is valid")
+    })
+
+  cmd
+    .command("preview")
+    .description("preview theme status bars by mode")
+    .option("--file <file>", "theme file path")
+    .action(async (options) => {
+      const ctx = await buildContext({ themeFile: options.file ?? null })
+      printContextWarnings(ctx)
+      const theme = ctx.themeState.theme
+      const config = ctx.configState.config
+      const modes = ["ask", "plan", "agent", "longagent"]
+      for (const mode of modes) {
+        const line = renderStatusBar({
+          mode,
+          model: "anthropic/claude-sonnet-4.5",
+          permission: "guarded",
+          tokenMeter: {
+            estimated: false,
+            turn: { input: 180, output: 240 },
+            session: { input: 1240, output: 2110 },
+            global: { input: 8920, output: 11110 }
+          },
+          aggregation: config.usage.aggregation,
+          cost: 0.0234,
+          showCost: config.ui.status.show_cost,
+          showTokenMeter: config.ui.status.show_token_meter,
+          theme
+        })
+        console.log(line)
+      }
+      console.log(`theme source: ${ctx.themeState.source}`)
+    })
+
+  return cmd
+}

package/src/commands/usage.mjs

@@ -0,0 +1,91 @@
+import path from "node:path"
+import { writeFile } from "node:fs/promises"
+import { Command } from "commander"
+import { exportUsageCsv, readUsageStore, resetUsage } from "../usage/usage-meter.mjs"
+import { buildContext } from "../context.mjs"
+
+function printUsageLine(scope, usage) {
+  console.log(
+    `${scope.padEnd(12)} input=${usage.input} output=${usage.output} cacheRead=${usage.cacheRead} cacheWrite=${usage.cacheWrite} cost=$${usage.cost.toFixed(4)} turns=${usage.turns}`
+  )
+}
+
+export function createUsageCommand() {
+  const cmd = new Command("usage").description("inspect and manage token/cost usage")
+
+  cmd
+    .command("show")
+    .description("show usage summary")
+    .option("--session <id>", "show only one session")
+    .option("--json", "print as JSON", false)
+    .action(async (options) => {
+      const store = await readUsageStore()
+      const ctx = await buildContext().catch(() => null)
+      const budget = ctx?.configState?.config?.usage?.budget || {}
+      if (options.json) {
+        if (options.session) {
+          console.log(JSON.stringify(store.sessions[options.session] ?? null, null, 2))
+          return
+        }
+        console.log(JSON.stringify(store, null, 2))
+        return
+      }
+      printUsageLine("global", store.global)
+      if (budget.global_usd) {
+        const ratio = (store.global.cost / budget.global_usd) * 100
+        console.log(`global budget: $${store.global.cost.toFixed(4)} / $${budget.global_usd} (${ratio.toFixed(1)}%)`)
+      }
+      if (options.session) {
+        const session = store.sessions[options.session]
+        if (!session) {
+          console.error(`session not found: ${options.session}`)
+          process.exitCode = 1
+          return
+        }
+        printUsageLine(`session:${options.session}`, session)
+        if (budget.session_usd) {
+          const ratio = (session.cost / budget.session_usd) * 100
+          console.log(`session budget: $${session.cost.toFixed(4)} / $${budget.session_usd} (${ratio.toFixed(1)}%)`)
+        }
+        return
+      }
+      for (const [sessionId, usage] of Object.entries(store.sessions)) {
+        printUsageLine(`session:${sessionId}`, usage)
+      }
+    })
+
+  cmd
+    .command("reset")
+    .description("reset usage counters")
+    .option("--session <id>", "reset only one session")
+    .action(async (options) => {
+      await resetUsage(options.session ?? null)
+      console.log(options.session ? `usage reset: ${options.session}` : "usage reset: all")
+    })
+
+  cmd
+    .command("export")
+    .description("export usage as json or csv")
+    .option("--format <format>", "json|csv", "json")
+    .option("--out <file>", "output file path")
+    .action(async (options) => {
+      const format = String(options.format).toLowerCase()
+      const outFile = path.resolve(options.out ?? `usage-export.${format}`)
+      if (format === "json") {
+        const store = await readUsageStore()
+        await writeFile(outFile, JSON.stringify(store, null, 2) + "\n", "utf8")
+        console.log(`usage exported: ${outFile}`)
+        return
+      }
+      if (format === "csv") {
+        const csv = await exportUsageCsv()
+        await writeFile(outFile, csv, "utf8")
+        console.log(`usage exported: ${outFile}`)
+        return
+      }
+      console.error("unsupported format, expected json or csv")
+      process.exitCode = 1
+    })
+
+  return cmd
+}

package/src/config/defaults.mjs

@@ -0,0 +1,195 @@
+export const DEFAULT_CONFIG = {
+  language: "en",
+  provider: {
+    default: "openai",
+    openai: {
+      base_url: "https://api.openai.com/v1",
+      api_key_env: "OPENAI_API_KEY",
+      default_model: "gpt-5.3-codex",
+      models: ["gpt-5.3-codex", "gpt-5.2"],
+      timeout_ms: 120000,
+      stream_idle_timeout_ms: 120000,
+      max_tokens: 32768,
+      context_limit: null,
+      retry_attempts: 3,
+      retry_base_delay_ms: 800,
+      stream: true,
+      thinking: null
+    },
+    anthropic: {
+      base_url: "https://api.anthropic.com/v1",
+      api_key_env: "ANTHROPIC_API_KEY",
+      default_model: "claude-opus-4-6",
+      models: ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5-20251001", "claude-opus-4-6"],
+      timeout_ms: 120000,
+      stream_idle_timeout_ms: 120000,
+      max_tokens: 32768,
+      context_limit: null,
+      retry_attempts: 3,
+      retry_base_delay_ms: 800,
+      stream: true,
+      thinking: null
+    },
+    ollama: {
+      base_url: "http://localhost:11434",
+      api_key_env: "",
+      default_model: "llama3.1",
+      timeout_ms: 300000,
+      stream_idle_timeout_ms: 300000,
+      max_tokens: 32768,
+      context_limit: null,
+      retry_attempts: 1,
+      retry_base_delay_ms: 1000,
+      stream: true,
+      thinking: null
+    },
+    model_context: {}
+  },
+  agent: {
+    default_mode: "agent",
+    max_steps: 8,
+    longagent: {
+      max_iterations: 0,
+      no_progress_warning: 3,
+      no_progress_limit: 5,
+      max_stage_recoveries: 3,
+      heartbeat_timeout_ms: 120000,
+      checkpoint_interval: 5,
+      parallel: {
+        enabled: true,
+        max_concurrency: 3,
+        stage_pass_rule: "all_success",
+        task_timeout_ms: 600000,
+        task_max_retries: 2
+      },
+      planner: {
+        intake_questions: {
+          enabled: true,
+          max_rounds: 6
+        },
+        ask_user_after_plan_frozen: false
+      },
+      resume_incomplete_files: true,
+      scaffold: {
+        enabled: true
+      },
+      git: {
+        enabled: "ask",
+        auto_branch: true,
+        auto_commit_stages: true,
+        auto_merge: true,
+        branch_prefix: "kkcode"
+      },
+      usability_gates: {
+        prompt_user: "first_run",
+        build: { enabled: true },
+        test: { enabled: true },
+        review: { enabled: true },
+        health: { enabled: true },
+        budget: { enabled: true }
+      }
+    },
+    subagents: {},
+    routing: {
+      categories: {}
+    }
+  },
+  mcp: {
+    servers: {},
+    auto_discover: true,
+    timeout_ms: 30000
+  },
+  skills: {
+    enabled: true,
+    dirs: [".kkcode/skills"]
+  },
+  permission: {
+    default_policy: "ask",
+    non_tty_default: "deny",
+    rules: []
+  },
+  storage: {
+    session_shard_enabled: true,
+    flush_interval_ms: 1000,
+    event_rotate_mb: 32,
+    event_retain_days: 14
+  },
+  background: {
+    mode: "worker_process",
+    worker_timeout_ms: 900000,
+    max_parallel: 2
+  },
+  runtime: {
+    tool_registry_cache_ttl_ms: 30000,
+    mcp_refresh_ttl_ms: 60000
+  },
+  tool: {
+    sources: {
+      builtin: true,
+      local: true,
+      mcp: true,
+      plugin: true
+    },
+    write_lock: {
+      mode: "file_lock",
+      wait_timeout_ms: 120000
+    },
+    local_dirs: [".kkcode/tools", ".kkcode/tool"],
+    plugin_dirs: [".kkcode/plugins", ".kkcode/plugin"]
+  },
+  session: {
+    max_history: 30,
+    recovery: true,
+    compaction_threshold_ratio: 0.7,
+    compaction_threshold_messages: 50,
+    context_cache_points: true
+  },
+  review: {
+    sort: "risk_first",
+    default_lines: 80,
+    max_expand_lines: 1200,
+    risk_weights: {
+      sensitive_path: 4,
+      large_change: 3,
+      medium_change: 2,
+      small_change: 1,
+      executable_script: 2,
+      command_pattern: 3
+    }
+  },
+  usage: {
+    pricing_file: null,
+    aggregation: ["turn", "session", "global"],
+    budget: {
+      session_usd: null,
+      global_usd: null,
+      warn_at_percent: 80,
+      strategy: "warn"
+    }
+  },
+  ui: {
+    theme_file: null,
+    mode_colors: {
+      ask: "#8da3b9",
+      plan: "#00b7c2",
+      agent: "#2ac26f",
+      longagent: "#ff7a33"
+    },
+    layout: "compact",
+    markdown_render: true,
+    status: {
+      show_cost: true,
+      show_token_meter: true
+    }
+  }
+}
+
+export const VALID_PROVIDER_TYPES = ["openai", "anthropic", "ollama", "openai-compatible"]
+
+import { listProviders } from "../provider/router.mjs"
+export function getValidProviderTypes() {
+  return listProviders()
+}
+export const VALID_MODES = ["ask", "plan", "agent", "longagent"]
+export const VALID_REVIEW_SORT = ["risk_first", "time_order", "file_order"]
+export const VALID_LANGUAGES = ["en", "zh"]

package/src/config/import-config.mjs

@@ -0,0 +1,76 @@
+import { DEFAULT_CONFIG } from "./defaults.mjs"
+
+function mergeObject(base, override) {
+  if (override === undefined || override === null) return base
+  if (Array.isArray(override)) return [...override]
+  if (!base || typeof base !== "object" || Array.isArray(base)) return override
+  if (typeof override !== "object") return override
+  const out = { ...base }
+  for (const key of Object.keys(override)) {
+    out[key] = mergeObject(base[key], override[key])
+  }
+  return out
+}
+
+function normalizePermissionRules(inputRules = {}) {
+  const rules = []
+  for (const [tool, value] of Object.entries(inputRules)) {
+    if (typeof value !== "boolean") continue
+    rules.push({
+      tool,
+      action: value ? "allow" : "deny"
+    })
+  }
+  return rules
+}
+
+export function importConfig(input = {}) {
+  const next = structuredClone(DEFAULT_CONFIG)
+
+  if (input.llm) {
+    if (input.llm.default_provider_type) next.provider.default = input.llm.default_provider_type
+    if (input.llm.max_steps) next.agent.max_steps = Number(input.llm.max_steps)
+
+    for (const key of ["openai", "anthropic"]) {
+      if (!input.llm[key]) continue
+      const src = input.llm[key]
+      const dst = next.provider[key]
+      if (src.base_url) dst.base_url = src.base_url
+      if (src.api_key_env) dst.api_key_env = src.api_key_env
+      if (src.default_model) dst.default_model = src.default_model
+    }
+  }
+
+  if (input.longagent?.max_iterations !== undefined) {
+    next.agent.longagent.max_iterations = Number(input.longagent.max_iterations)
+  }
+
+  if (input.usage) {
+    if (input.usage.pricing_file !== undefined) next.usage.pricing_file = input.usage.pricing_file
+    if (Array.isArray(input.usage.aggregation)) next.usage.aggregation = [...input.usage.aggregation]
+  }
+
+  if (input.ui) {
+    if (input.ui.layout) next.ui.layout = input.ui.layout
+    if (input.ui.theme?.file !== undefined) next.ui.theme_file = input.ui.theme.file
+    if (input.ui.theme?.mode_colors) next.ui.mode_colors = mergeObject(next.ui.mode_colors, input.ui.theme.mode_colors)
+    if (input.ui.status) next.ui.status = mergeObject(next.ui.status, input.ui.status)
+    if (input.ui.review?.sort) next.review.sort = input.ui.review.sort
+    if (input.ui.diff_preview?.default_lines) next.review.default_lines = Number(input.ui.diff_preview.default_lines)
+    if (input.ui.diff_preview?.max_expand_lines) next.review.max_expand_lines = Number(input.ui.diff_preview.max_expand_lines)
+  }
+
+  if (input.agents && typeof input.agents === "object") {
+    next.agent.subagents = mergeObject(next.agent.subagents, input.agents)
+  }
+
+  if (input.tools && typeof input.tools === "object") {
+    next.permission.rules.push(...normalizePermissionRules(input.tools))
+  }
+
+  if (input.permission?.rules && Array.isArray(input.permission.rules)) {
+    next.permission.rules.push(...input.permission.rules)
+  }
+
+  return next
+}