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

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.1)](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,42 @@ 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.1`
 **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.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.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.1",
   "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",

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/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.1"
+export const RELEASE_LABEL = "0.2.3 Preview V1"