@kkelly-offical/kkcode 0.2.1 → 0.2.3-preview.2

package/README.md

@@ -1,6 +1,6 @@
 # kkcode
 
-[![npm version](https://img.shields.io/npm/v/@kkelly-offical/kkcode?label=v0.2.1)](https://www.npmjs.com/package/@kkelly-offical/kkcode)
+[![npm version](https://img.shields.io/npm/v/@kkelly-offical/kkcode?label=v0.2.3-preview.2)](https://www.npmjs.com/package/@kkelly-offical/kkcode)
 [![GitHub Release](https://img.shields.io/github/v/release/kkelly-offical/kkcode)](https://github.com/kkelly-offical/kkcode/releases)
 ![Node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
 ![License](https://img.shields.io/badge/License-GPL--3.0-blue)
@@ -351,20 +351,44 @@ Run `kkcode --help` or `kkcode <command> --help` for the full surface.
 
 ---
 
+<a id="updates"></a>
+## Updates / 更新
+
+KKCode checks npm dist-tags in the background on startup and caches the result under `~/.kkcode/update-state.json`. By default it only prints a notice; it does not modify your global install unless you explicitly run the updater.
+
+```bash
+kkcode update --check
+kkcode update --install --channel latest
+kkcode update --install --channel preview
+```
+
+Config:
+
+```yaml
+update:
+  enabled: true
+  notify_on_startup: true
+  auto_install: false
+  channel: "latest"
+  check_interval_hours: 12
+```
+
 <a id="release-status"></a>
 ## Release Status / 发布状态
 
-**Current stable / 当前稳定版本**: `v0.2.1`
+**Current preview / 当前预览版本**: `v0.2.3-preview.2`
 **Latest releases / 最新发布**: [GitHub Releases](https://github.com/kkelly-offical/kkcode/releases)  
 **Package / 包地址**: [npm](https://www.npmjs.com/package/@kkelly-offical/kkcode)
 
 **English**
-- `0.2.1` rebuilds kkcode around Assistant as the default general-purpose lane, with dedicated Agent and LongAgent modes for coding work.
-- The public Ask lane has been removed; question, explanation, and lightweight personal-assistant tasks now route to Assistant.
+- `0.2.3-preview.2` is the Preview V2 context release: compaction now merges prior context state, keeps evidence before pruning, and preserves turn metadata for reliable recent-turn retention.
+- `0.2.3-preview.1` is the Preview V1 updater release: kkcode can check npm dist-tags at startup and exposes `kkcode update` for manual upgrades.
+- `0.2.1` rebuilt kkcode around Assistant as the default general-purpose lane, with dedicated Agent and LongAgent modes for coding work.
 
 **中文**
+- `0.2.3-preview.2` 是 Preview V2 上下文版本：压缩会合并旧上下文状态，在裁剪前保留关键证据，并保留 turn 元数据以稳定保留最近对话。
+- `0.2.3-preview.1` 是 Preview V1 更新器版本：kkcode 可在启动时检查 npm dist-tag，并提供 `kkcode update` 手动升级入口。
 - `0.2.1` 将 kkcode 重构为以 Assistant 为默认入口的通用个人助手，同时保留专门面向代码工作的 Agent 和 LongAgent 模式。
-- 公共 Ask 通道已移除；问答、解释和轻量个人助手任务现在统一路由到 Assistant。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkelly-offical/kkcode",
-  "version": "0.2.1",
+  "version": "0.2.3-preview.2",
   "description": "CLI-first personal assistant with dedicated coding and LongAgent modes for governed terminal workflows, MCP integrations, and extensible automation.",
   "type": "module",
   "packageManager": "pnpm@10.5.2",
@@ -8,7 +8,7 @@
   "author": "kkelly-offical",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kkelly-offical/kkcode.git"
+    "url": "git+https://github.com/kkelly-offical/kkcode.git"
   },
   "homepage": "https://github.com/kkelly-offical/kkcode",
   "bugs": {
@@ -25,7 +25,7 @@
     "mcp"
   ],
   "bin": {
-    "kkcode": "./src/index.mjs"
+    "kkcode": "src/index.mjs"
   },
   "files": [
     "src/",

package/src/commands/update.mjs

@@ -0,0 +1,32 @@
+import { Command } from "commander"
+import { loadConfig } from "../config/load-config.mjs"
+import { PACKAGE_VERSION } from "../version.mjs"
+import { checkForUpdate, installUpdate, updateMessage } from "../update/checker.mjs"
+
+export function createUpdateCommand() {
+  return new Command("update")
+    .description("check for and install kkcode updates")
+    .option("--check", "only check for updates", false)
+    .option("--install", "install the selected update", false)
+    .option("--channel <channel>", "npm dist-tag to follow", null)
+    .option("--json", "print structured result", false)
+    .action(async (options) => {
+      const state = await loadConfig(process.cwd())
+      const config = { ...state.config, update: { ...(state.config.update || {}) } }
+      if (options.channel) config.update.channel = options.channel
+      const result = await checkForUpdate(config, { force: true, currentVersion: PACKAGE_VERSION })
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2))
+      } else if (result.hasUpdate) {
+        console.log(updateMessage(result))
+      } else {
+        console.log(`kkcode is up to date (${result.currentVersion}) on ${result.channel}`)
+      }
+
+      if (options.check || !options.install) return
+      if (!result.hasUpdate) return
+      const installed = await installUpdate(config, { channel: result.channel })
+      if (!installed.ok) throw new Error(`update install failed: ${installed.error}`)
+      console.log(`installed kkcode ${result.latestVersion}; restart your shell or kkcode session if needed`)
+    })
+}

package/src/config/defaults.mjs

@@ -252,6 +252,15 @@ export const DEFAULT_CONFIG = {
       strategy: "warn"
     }
   },
+  update: {
+    enabled: true,
+    notify_on_startup: true,
+    auto_install: false,
+    channel: "latest",
+    check_interval_hours: 12,
+    registry: "https://registry.npmjs.org",
+    timeout_ms: 2500
+  },
   ui: {
     theme_file: null,
     mode_colors: {

package/src/config/schema.mjs

@@ -512,6 +512,19 @@ export function validateConfig(config) {
     }
   }
 
+  if (config.update !== undefined) {
+    if (!isObj(config.update)) err(errors, "update", "must be object")
+    else {
+      if (config.update.enabled !== undefined && typeof config.update.enabled !== "boolean") err(errors, "update.enabled", "must be boolean")
+      if (config.update.notify_on_startup !== undefined && typeof config.update.notify_on_startup !== "boolean") err(errors, "update.notify_on_startup", "must be boolean")
+      if (config.update.auto_install !== undefined && typeof config.update.auto_install !== "boolean") err(errors, "update.auto_install", "must be boolean")
+      if (config.update.channel !== undefined && typeof config.update.channel !== "string") err(errors, "update.channel", "must be string")
+      if (config.update.registry !== undefined && typeof config.update.registry !== "string") err(errors, "update.registry", "must be string")
+      if (config.update.check_interval_hours !== undefined) checkInt(errors, "update.check_interval_hours", config.update.check_interval_hours, 0)
+      if (config.update.timeout_ms !== undefined) checkInt(errors, "update.timeout_ms", config.update.timeout_ms, 100)
+    }
+  }
+
   if (config.ui !== undefined) {
     if (!isObj(config.ui)) err(errors, "ui", "must be object")
     else {

package/src/index.mjs

@@ -20,6 +20,8 @@ import { createInitCommand } from "./commands/init.mjs"
 import { createAuditCommand } from "./commands/audit.mjs"
 import { createSkillCommand } from "./commands/skill.mjs"
 import { startRepl } from "./repl.mjs"
+import { PACKAGE_VERSION } from "./version.mjs"
+import { createUpdateCommand } from "./commands/update.mjs"
 
 async function main() {
   const hasTrust = process.argv.includes("--trust")
@@ -55,7 +57,7 @@ async function main() {
   }
 
   const program = new Command()
-  program.name("kkcode").description("kkcode CLI").version("0.2.1")
+  program.name("kkcode").description("kkcode CLI").version(PACKAGE_VERSION)
   program.addCommand(createChatCommand())
   program.addCommand(createThemeCommand())
   program.addCommand(createUsageCommand())
@@ -75,6 +77,7 @@ async function main() {
   program.addCommand(createAuditCommand())
   program.addCommand(createInitCommand())
   program.addCommand(createSkillCommand())
+  program.addCommand(createUpdateCommand())
   await program.parseAsync(process.argv)
 }
 

package/src/mcp/constants.mjs

@@ -1,2 +1,4 @@
+import { PACKAGE_VERSION } from "../version.mjs"
+
 export const MCP_PROTOCOL_VERSION = "2024-11-05"
-export const MCP_CLIENT_INFO = { name: "kkcode", version: "0.2.1" }
+export const MCP_CLIENT_INFO = { name: "kkcode", version: PACKAGE_VERSION }

package/src/repl.mjs

@@ -1,3 +1,5 @@
+import { PACKAGE_VERSION } from "./version.mjs"
+import { maybeNotifyUpdateOnStartup } from "./update/checker.mjs"
 import { stdin as input, stdout as output } from "node:process"
 import { createInterface } from "node:readline/promises"
 import { emitKeypressEvents } from "node:readline"
@@ -3310,10 +3312,11 @@ export async function startRepl({ trust = false } = {}) {
   const { checkWorkspaceTrust } = await import("./permission/workspace-trust.mjs")
   const trustState = await checkWorkspaceTrust({ cwd: process.cwd(), cliTrust: trust, isTTY: process.stdin.isTTY })
 
-  const splash = startSplash({ version: "v0.2.1" })
+  const splash = startSplash({ version: `v${PACKAGE_VERSION}` })
 
   const ctx = await buildContext({ trust, trustState })
   printContextWarnings(ctx)
+  void maybeNotifyUpdateOnStartup(ctx.configState.config, { currentVersion: PACKAGE_VERSION })
 
   splash.update("loading tools & MCP servers...")
   await ToolRegistry.initialize({ config: ctx.configState.config, cwd: process.cwd() })

package/src/session/compaction.mjs

@@ -5,36 +5,36 @@ import { saveCheckpoint } from "./checkpoint.mjs"
 import { recordTurn } from "../usage/usage-meter.mjs"
 import { loadPricing, calculateCost } from "../usage/pricing.mjs"
 
-const COMPACTION_SYSTEM = `You are a conversation summarizer. Create a structured summary preserving all critical information for continued work.
+const COMPACTION_SYSTEM = `You are a conversation summarizer. Create a structured, merge-safe summary preserving all critical information for continued work.
 
 ## Output Format
 
+Return exactly:
+
+<context-state>
+{
+  "goal": "The user's current overall goal",
+  "completed": ["Completed work with specific file paths, function names, and line numbers"],
+  "in_progress": ["Current work being done"],
+  "files_modified": [{"path":"path/to/file","changes":["specific change"]}],
+  "key_decisions": ["Decision, constraint, or user preference"],
+  "errors_resolved": ["Error -> fix applied"],
+  "evidence": ["Important command output, test result, provider error, or exact failure detail"],
+  "next_steps": ["Specific next action item"]
+}
+</context-state>
+
 <summary>
-<goal>The user's overall goal or current task</goal>
-<completed>
-- Completed task with specific details (file paths, function names, line numbers)
-</completed>
-<in_progress>Current work being done, if any</in_progress>
-<files_modified>
-- path/to/file: specific change description
-</files_modified>
-<key_decisions>
-- Decision and reasoning
-- User preferences or constraints
-</key_decisions>
-<errors_resolved>
-- Error description → fix applied
-</errors_resolved>
-<next_steps>
-- Specific next action items
-</next_steps>
+Concise human-readable continuation summary.
 </summary>
 
 Rules:
 - Use the SAME LANGUAGE as the conversation
+- Merge the prior context state with the new conversation delta; do not summarize the prior state as another chat message
 - Preserve ALL file paths, function names, variable names, and technical identifiers exactly
 - Include specific code changes, not just "modified file X"
 - Omit tool call metadata and message formatting details
+- Preserve exact errors, failing test names, package versions, release labels, and user constraints in evidence
 - Be concise but never drop actionable information`
 
 const DEFAULT_THRESHOLD_MESSAGES = 50
@@ -42,6 +42,118 @@ const DEFAULT_THRESHOLD_RATIO = 0.7
 const DEFAULT_KEEP_RECENT = 6
 const DEFAULT_KEEP_RECENT_TURNS = 3
 const TOOL_RESULT_PREVIEW_LIMIT = 200
+const EVIDENCE_PREVIEW_LIMIT = 900
+const PATH_RE = /(?:^|\s)([A-Za-z0-9_.@~/-]+\.(?:mjs|js|ts|tsx|jsx|json|yaml|yml|md|txt|rs|go|py|sh|toml|lock))(?:[:\s]|$)/g
+const IMPORTANT_LINE_RE = /(error|failed|failure|exception|traceback|assert|reject|denied|unauthorized|context|compact|version|publish|npm|test|lint|typecheck|diff|modified)/i
+
+export function isCompactionSummaryMessage(msg) {
+  const content = msg?.content
+  if (typeof content === "string") return content.includes("<compaction-summary")
+  if (Array.isArray(content)) {
+    return content.some((block) => {
+      if (typeof block === "string") return block.includes("<compaction-summary")
+      return block?.type === "text" && typeof block.text === "string" && block.text.includes("<compaction-summary")
+    })
+  }
+  return false
+}
+
+export function extractCompactionSummary(content) {
+  const text = Array.isArray(content)
+    ? content.map((block) => typeof block === "string" ? block : (block?.text || block?.content || "")).join("\n")
+    : String(content || "")
+  const match = text.match(/<compaction-summary(?:\s[^>]*)?>\s*([\s\S]*?)\s*<\/compaction-summary>/i)
+  return (match ? match[1] : "").trim()
+}
+
+function clip(text, limit = EVIDENCE_PREVIEW_LIMIT) {
+  const raw = String(text || "")
+  if (raw.length <= limit) return raw
+  return raw.slice(0, limit) + "... [truncated " + raw.length + " chars]"
+}
+
+function extractPaths(text) {
+  const paths = new Set()
+  let match
+  PATH_RE.lastIndex = 0
+  while ((match = PATH_RE.exec(String(text || ""))) !== null) {
+    paths.add(match[1])
+    if (paths.size >= 12) break
+  }
+  return [...paths]
+}
+
+function importantLines(text, limit = 12) {
+  return String(text || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && IMPORTANT_LINE_RE.test(line))
+    .slice(0, limit)
+}
+
+export function collectEvidenceLedger(messages, previewLimit = EVIDENCE_PREVIEW_LIMIT) {
+  const evidence = []
+  for (const msg of messages) {
+    const content = msg.content
+    const blocks = Array.isArray(content) ? content : [{ type: "text", text: content }]
+    for (const block of blocks) {
+      const raw = String(block?.content || block?.text || "")
+      if (!raw) continue
+      if (block.type === "tool_result") {
+        const lines = importantLines(raw)
+        const paths = extractPaths(raw)
+        if (block.is_error || lines.length || paths.length) {
+          evidence.push([
+            "- role=" + msg.role + " tool_result" + (block.is_error ? " ERROR" : ""),
+            paths.length ? "  paths: " + paths.join(", ") : "",
+            lines.length ? "  key_lines:\n" + lines.map((line) => "    " + clip(line, 220)).join("\n") : "  preview: " + clip(raw, previewLimit)
+          ].filter(Boolean).join("\n"))
+        }
+      } else if (typeof content === "string" && raw.length > 1000) {
+        const lines = importantLines(raw)
+        const paths = extractPaths(raw)
+        if (lines.length || paths.length) {
+          evidence.push([
+            "- role=" + msg.role + " long_text",
+            paths.length ? "  paths: " + paths.join(", ") : "",
+            lines.length ? "  key_lines:\n" + lines.map((line) => "    " + clip(line, 220)).join("\n") : ""
+          ].filter(Boolean).join("\n"))
+        }
+      }
+      if (evidence.length >= 20) return evidence
+    }
+  }
+  return evidence
+}
+
+export function buildCompactionPrompt({ previousSummary = "", messages, evidence = [] }) {
+  const transcript = messages.map((m) => {
+    const content = m.content
+    if (Array.isArray(content)) {
+      return "[" + m.role + "]: " + content.map((b) => {
+        if (b.type === "text") return b.text || ""
+        if (b.type === "tool_use") return "[tool_use:" + b.name + "(" + JSON.stringify(b.input || {}).slice(0, 120) + ")]"
+        if (b.type === "tool_result") return "[tool_result:" + (b.is_error ? "ERROR " : "") + (b.content || "") + "]"
+        return ""
+      }).filter(Boolean).join("\n")
+    }
+    return "[" + m.role + "]: " + content
+  }).join("\n\n")
+
+  return [
+    "<prior-context-state>",
+    previousSummary || "No prior compacted context.",
+    "</prior-context-state>",
+    "",
+    "<evidence-ledger>",
+    evidence.length ? evidence.join("\n") : "No extracted evidence ledger.",
+    "</evidence-ledger>",
+    "",
+    "<conversation-delta>",
+    transcript,
+    "</conversation-delta>"
+  ].join("\n")
+}
 
 // Estimate tokens from a string, accounting for CJK characters (~1.5 chars/token vs ~4 for Latin)
 export function estimateStringTokens(str) {
@@ -193,8 +305,12 @@ export async function compactSession({
   baseUrl = null,
   apiKeyEnv = null
 }) {
-  const history = await getConversationHistory(sessionId, 9999)
+  const history = await getConversationHistory(sessionId, 9999, { includeMetadata: true })
   if (history.length <= keepRecent + 2) return { compacted: false, reason: "too few messages" }
+  const previousSummary = isCompactionSummaryMessage(history[0])
+    ? extractCompactionSummary(history[0].content)
+    : ""
+  const workingHistory = previousSummary ? history.slice(1) : history
 
   // Turn-based split: keep last keepRecentTurns complete turns
   // A "turn" = one user interaction cycle (user msg + model response + all tool calls)
@@ -202,7 +318,7 @@ export async function compactSession({
   let splitIdx
   const turnIds = []
   const seenTurns = new Set()
-  for (const msg of history) {
+  for (const msg of workingHistory) {
     if (msg.turnId && !seenTurns.has(msg.turnId)) {
       seenTurns.add(msg.turnId)
       turnIds.push(msg.turnId)
@@ -210,29 +326,19 @@ export async function compactSession({
   }
   if (turnIds.length > keepRecentTurns) {
     const keepFromTurnId = turnIds[turnIds.length - keepRecentTurns]
-    splitIdx = history.findIndex(msg => msg.turnId === keepFromTurnId)
-    if (splitIdx < 0) splitIdx = history.length - keepRecent
+    splitIdx = workingHistory.findIndex(msg => msg.turnId === keepFromTurnId)
+    if (splitIdx < 0) splitIdx = workingHistory.length - keepRecent
   } else {
     // Fallback: not enough turns, use message count
-    splitIdx = history.length - keepRecent
+    splitIdx = workingHistory.length - keepRecent
   }
-  const toSummarize = history.slice(0, splitIdx)
-  const kept = history.slice(splitIdx)
+  const toSummarize = workingHistory.slice(0, splitIdx)
+  const kept = workingHistory.slice(splitIdx)
 
-  // Layer 1: prune large tool outputs before sending to LLM
+  // Layer 1: extract exact evidence, then prune large tool outputs before sending to LLM
+  const evidence = collectEvidenceLedger(toSummarize)
   const pruned = pruneForSummary(toSummarize)
-  const summaryPrompt = pruned.map((m) => {
-    const content = m.content
-    if (Array.isArray(content)) {
-      return `[${m.role}]: ${content.map((b) => {
-        if (b.type === "text") return b.text || ""
-        if (b.type === "tool_use") return `[tool_use:${b.name}(${JSON.stringify(b.input || {}).slice(0, 120)})]`
-        if (b.type === "tool_result") return `[tool_result:${b.is_error ? "ERROR " : ""}${b.content || ""}]`
-        return ""
-      }).filter(Boolean).join("\n")}`
-    }
-    return `[${m.role}]: ${content}`
-  }).join("\n\n")
+  const summaryPrompt = buildCompactionPrompt({ previousSummary, messages: pruned, evidence })
 
   const hookPayload = await HookBus.sessionCompacting({
     sessionId,
@@ -266,7 +372,7 @@ export async function compactSession({
   // Replace all messages with: [summary] + [kept recent messages]
   const summaryMessage = {
     role: "user",
-    content: `<compaction-summary>\n${summaryText}\n</compaction-summary>`
+    content: `<compaction-summary version="2">\n${summaryText}\n</compaction-summary>`
   }
   await replaceMessages(sessionId, [summaryMessage, ...kept])
 
@@ -285,8 +391,10 @@ export async function compactSession({
     compactedAt: Date.now(),
     summarizeCount: toSummarize.length,
     keepCount: kept.length,
-    summaryVersion: 1,
-    summaryLength: summaryText.length
+    summaryVersion: 2,
+    summaryLength: summaryText.length,
+    previousSummaryLength: previousSummary.length,
+    evidenceCount: evidence.length
   })
 
   return {

package/src/session/store.mjs

@@ -323,7 +323,7 @@ export async function listSessions({ cwd = null, limit = 100, includeChildren =
   })
 }
 
-export async function getConversationHistory(sessionId, limit = 30) {
+export async function getConversationHistory(sessionId, limit = 30, options = {}) {
   return withLock(async () => {
     await ensureLoadedUnsafe()
     const data = await loadSessionDataUnsafe(sessionId)
@@ -339,10 +339,19 @@ export async function getConversationHistory(sessionId, limit = 30) {
     const sliced = firstIsCompaction
       ? [msgs[0], ...msgs.slice(1).slice(-limit)]
       : msgs.slice(-limit)
-    return sliced.map((msg) => ({
-      role: msg.role,
-      content: msg.content
-    }))
+    return sliced.map((msg) => {
+      const base = {
+        role: msg.role,
+        content: msg.content
+      }
+      if (!options.includeMetadata) return base
+      return {
+        ...base,
+        turnId: msg.turnId,
+        step: msg.step,
+        synthetic: msg.synthetic
+      }
+    })
   })
 }
 

package/src/storage/paths.mjs

@@ -111,6 +111,10 @@ export function auditStorePath() {
   return path.join(userRootDir(), "audit-log.json")
 }
 
+export function updateStatePath() {
+  return path.join(userRootDir(), "update-state.json")
+}
+
 export async function ensureUserRoot() {
   await mkdir(userRootDir(), { recursive: true })
 }

package/src/update/checker.mjs

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process"
+import { readFile, writeFile } from "node:fs/promises"
+import { dirname } from "node:path"
+import { mkdir } from "node:fs/promises"
+import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.mjs"
+import { updateStatePath } from "../storage/paths.mjs"
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org"
+const DEFAULT_TIMEOUT_MS = 2500
+
+function normalizeRegistry(registry = DEFAULT_REGISTRY) {
+  return String(registry || DEFAULT_REGISTRY).replace(/\/+$/, "")
+}
+
+function encodePackageName(name) {
+  return String(name).replace("/", "%2F")
+}
+
+function parseVersion(version) {
+  const match = String(version || "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/)
+  if (!match) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : part)) : []
+  }
+}
+
+function compareIdentifier(a, b) {
+  if (a === b) return 0
+  const aNum = typeof a === "number"
+  const bNum = typeof b === "number"
+  if (aNum && bNum) return a > b ? 1 : -1
+  if (aNum) return -1
+  if (bNum) return 1
+  return String(a) > String(b) ? 1 : -1
+}
+
+export function compareVersions(a, b) {
+  const av = parseVersion(a)
+  const bv = parseVersion(b)
+  if (!av || !bv) return String(a || "").localeCompare(String(b || ""))
+  for (const key of ["major", "minor", "patch"]) {
+    if (av[key] !== bv[key]) return av[key] > bv[key] ? 1 : -1
+  }
+  const aPre = av.prerelease
+  const bPre = bv.prerelease
+  if (!aPre.length && !bPre.length) return 0
+  if (!aPre.length) return 1
+  if (!bPre.length) return -1
+  const len = Math.max(aPre.length, bPre.length)
+  for (let i = 0; i < len; i++) {
+    if (aPre[i] === undefined) return -1
+    if (bPre[i] === undefined) return 1
+    const cmp = compareIdentifier(aPre[i], bPre[i])
+    if (cmp !== 0) return cmp
+  }
+  return 0
+}
+
+export function updateConfig(config = {}) {
+  return {
+    enabled: config.update?.enabled !== false,
+    notifyOnStartup: config.update?.notify_on_startup !== false,
+    autoInstall: Boolean(config.update?.auto_install),
+    channel: config.update?.channel || "latest",
+    checkIntervalHours: Number(config.update?.check_interval_hours ?? 12),
+    registry: config.update?.registry || DEFAULT_REGISTRY,
+    timeoutMs: Number(config.update?.timeout_ms ?? DEFAULT_TIMEOUT_MS)
+  }
+}
+
+async function readUpdateState(file = updateStatePath()) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"))
+  } catch {
+    return {}
+  }
+}
+
+async function writeUpdateState(state, file = updateStatePath()) {
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, `${JSON.stringify(state, null, 2)}\n`)
+}
+
+export async function fetchPackageMetadata({ packageName = PACKAGE_NAME, registry = DEFAULT_REGISTRY, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable in this Node runtime")
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), Math.max(100, Number(timeoutMs || DEFAULT_TIMEOUT_MS)))
+  try {
+    const url = `${normalizeRegistry(registry)}/${encodePackageName(packageName)}`
+    const res = await fetchImpl(url, {
+      headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
+      signal: controller.signal
+    })
+    if (!res.ok) throw new Error(`npm registry returned HTTP ${res.status}`)
+    return await res.json()
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export async function checkForUpdate(config = {}, options = {}) {
+  const cfg = updateConfig(config)
+  if (!cfg.enabled && !options.force) return { ok: false, skipped: true, reason: "disabled" }
+
+  const now = Number(options.now ?? Date.now())
+  const stateFile = options.stateFile || updateStatePath()
+  const state = options.state ?? await readUpdateState(stateFile)
+  const intervalMs = Math.max(0, cfg.checkIntervalHours) * 60 * 60 * 1000
+  if (!options.force && intervalMs > 0 && state.checkedAt && now - Date.parse(state.checkedAt) < intervalMs) {
+    return { ok: true, skipped: true, reason: "interval", state }
+  }
+
+  const metadata = await fetchPackageMetadata({
+    packageName: options.packageName || PACKAGE_NAME,
+    registry: cfg.registry,
+    timeoutMs: cfg.timeoutMs,
+    fetchImpl: options.fetchImpl
+  })
+  const distTags = metadata["dist-tags"] || {}
+  const latestVersion = distTags[cfg.channel] || distTags.latest || metadata.version
+  const currentVersion = options.currentVersion || PACKAGE_VERSION
+  const hasUpdate = Boolean(latestVersion && compareVersions(latestVersion, currentVersion) > 0)
+  const result = {
+    ok: true,
+    packageName: options.packageName || PACKAGE_NAME,
+    channel: cfg.channel,
+    currentVersion,
+    latestVersion,
+    hasUpdate,
+    installSpec: `${options.packageName || PACKAGE_NAME}@${cfg.channel}`,
+    checkedAt: new Date(now).toISOString()
+  }
+  await writeUpdateState(result, stateFile)
+  return result
+}
+
+export function updateMessage(result) {
+  if (!result?.hasUpdate) return null
+  return `Update available: kkcode ${result.currentVersion} -> ${result.latestVersion} (${result.channel}). Run: kkcode update --channel ${result.channel}`
+}
+
+export async function maybeNotifyUpdateOnStartup(config = {}, options = {}) {
+  const cfg = updateConfig(config)
+  if (!cfg.enabled || !cfg.notifyOnStartup || process.env.KKCODE_DISABLE_UPDATE_CHECK === "1") return null
+  try {
+    const result = await checkForUpdate(config, options)
+    const message = updateMessage(result)
+    if (message) {
+      const print = options.print || console.error
+      print(message)
+      if (cfg.autoInstall) {
+        const install = await installUpdate(config, { channel: result.channel, stdio: "ignore" })
+        if (install.ok) print(`kkcode update installed ${result.latestVersion}; restart kkcode to use it.`)
+        else print(`kkcode auto-update failed: ${install.error}`)
+      }
+    }
+    return result
+  } catch (error) {
+    if (options.verbose) (options.print || console.error)(`kkcode update check failed: ${error.message}`)
+    return { ok: false, error: error.message }
+  }
+}
+
+function runCommand(command, args, { cwd = process.cwd(), env = process.env, stdio = "inherit" } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, env, stdio, shell: process.platform === "win32" })
+    child.on("exit", (code) => resolve({ ok: code === 0, code }))
+    child.on("error", (error) => resolve({ ok: false, code: 1, error: error.message }))
+  })
+}
+
+export async function installUpdate(config = {}, options = {}) {
+  const cfg = updateConfig(config)
+  const channel = options.channel || cfg.channel || "latest"
+  const packageName = options.packageName || PACKAGE_NAME
+  const npm = options.npmCommand || process.env.npm_execpath || "npm"
+  const args = ["install", "-g", `${packageName}@${channel}`]
+  const result = await (options.runCommand || runCommand)(npm, args, options)
+  if (!result.ok) return { ok: false, code: result.code, error: result.error || `npm exited with ${result.code}` }
+  return { ok: true, command: npm, args }
+}

package/src/version.mjs

@@ -0,0 +1,3 @@
+export const PACKAGE_NAME = "@kkelly-offical/kkcode"
+export const PACKAGE_VERSION = "0.2.3-preview.2"
+export const RELEASE_LABEL = "0.2.3 Preview V2"