@hippox/codegenie 3.11.2026 → 3.13.2026

package/README.md

@@ -8,6 +8,13 @@
 npm install -g @hippox/codegenie
 ```
 
+预发布渠道：
+
+```bash
+npm install -g @hippox/codegenie@beta
+npm install -g @hippox/codegenie@alpha
+```
+
 安装完成后即可直接执行：
 
 ```bash
@@ -17,14 +24,33 @@ codegenie --version
 说明：
 
 - npm 安装会直接创建全局 `codegenie` 命令
-- 首次运行只会提取内置 kernel 到 `~/.codegenie/kernel`，不会再把二进制复制到 `~/.codegenie/bin`
+- 如果 npm 因 optionalDependencies 配置跳过了平台包，安装脚本会自动补装当前平台包
+- npm 安装阶段会预热 runtime assets；Windows 还会额外隐藏预热一次默认启动路径，因此安装时间会略长，但首次可见启动会更快
+- 首次运行通常不再需要解包和安装依赖；首次进入某个工作区时，仍可能有少量项目级初始化
+- 首次运行不会再把二进制复制到 `~/.codegenie/bin`
+- npm 安装/升级会清理旧安装残留和临时更新残留
 - `upgrade` 在 npm 安装场景下会提示或委托执行 npm 升级命令，不直接覆写 npm 全局目录
 
+## 卸载
+
+推荐顺序：
+
+```bash
+codegenie uninstall --yes
+npm uninstall -g @hippox/codegenie
+```
+
+说明：
+
+- `codegenie uninstall --yes` 删除 `~/.codegenie` 运行目录
+- `npm uninstall -g @hippox/codegenie` 删除 npm 全局命令和包记录
+- npm 卸载生命周期脚本会做最佳努力清理，但不同 npm 版本行为不完全一致，不应只依赖 `npm uninstall -g`
+
 ## 平台说明
 
-当前 staged 平台包：`@hippox/codegenie-win32-x64`
+当前 staged 平台包：`@hippox/codegenie-darwin-arm64`, `@hippox/codegenie-darwin-x64`, `@hippox/codegenie-win32-x64`
 
-- `baseline` 兼容构建不会通过 npm 分发，老 CPU 请改用独立二进制发布件
+- `baseline` 兼容构建不进入 npm 正式发布范围
 
 ## 发布说明
 

package/bin/codegenie.js

@@ -1,25 +1,68 @@
 #!/usr/bin/env node
 
-const { spawnSync } = require("child_process")
+const { spawn } = require("child_process")
+const { buildLaunchEnv } = require("../lib/launch.js")
 const { resolveBinary } = require("../lib/resolve-binary.js")
+const { shouldPrintStartupHint, startupHintText } = require("../lib/startup-hint.js")
+
+const SPINNER = ["\u2807", "\u280B", "\u2819", "\u2838", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"]
 
 function main() {
+  const argv = process.argv.slice(2)
+  const showHint = shouldPrintStartupHint(argv)
+
+  let spinnerInterval = null
+  let spinnerIdx = 0
+  if (showHint && process.stderr.isTTY) {
+    process.stderr.write("\x1b[?25l")
+    const draw = () => {
+      process.stderr.write(`\r  \x1b[36m\x1b[1mCodeGenie\x1b[0m  \x1b[2m${SPINNER[spinnerIdx++ % SPINNER.length]} Loading...\x1b[0m`)
+    }
+    draw()
+    spinnerInterval = setInterval(draw, 100)
+  } else if (showHint) {
+    process.stderr.write(startupHintText() + "\n")
+  }
+
   const resolved = resolveBinary()
-  const result = spawnSync(resolved.binaryPath, process.argv.slice(2), {
+
+  const child = spawn(resolved.binaryPath, argv, {
     stdio: "inherit",
-    env: {
-      ...process.env,
-      CODEGENIE_INSTALL_SOURCE: "npm",
-      CODEGENIE_NPM_PACKAGE: resolved.packageName,
-    },
+    env: buildLaunchEnv(resolved.packageName, resolved.platformDir, process.env),
+  })
+
+  child.on("spawn", () => {
+    if (spinnerInterval) {
+      clearInterval(spinnerInterval)
+      spinnerInterval = null
+    }
   })
 
-  if (result.error) {
-    console.error(`[codegenie] Failed to start ${resolved.packageName}: ${result.error.message}`)
+  child.on("error", (err) => {
+    if (spinnerInterval) {
+      clearInterval(spinnerInterval)
+    }
+    process.stderr.write("\r\x1b[K\x1b[?25h")
+    console.error(`[codegenie] Failed to start ${resolved.packageName}: ${err.message}`)
     process.exit(1)
-  }
+  })
 
-  process.exit(result.status ?? 1)
+  child.on("exit", (code, signal) => {
+    if (spinnerInterval) {
+      clearInterval(spinnerInterval)
+    }
+    if (signal) {
+      process.kill(process.pid, signal)
+    } else {
+      process.exit(code ?? 1)
+    }
+  })
+
+  function forwardSignal(sig) {
+    if (child.pid) child.kill(sig)
+  }
+  process.on("SIGINT", forwardSignal)
+  process.on("SIGTERM", forwardSignal)
 }
 
 main()

package/bin/postinstall.js

@@ -1,14 +1,83 @@
 #!/usr/bin/env node
 
-const { resolveBinary } = require("../lib/resolve-binary.js")
+const { execFileSync } = require("child_process")
+const { resolveBinary, resolvePackageName } = require("../lib/resolve-binary.js")
+const { prewarmBinary, warmStartupBinary } = require("../lib/prewarm.js")
+const packageJson = require("../package.json")
+
+function tryInstallPlatformPackage() {
+  let platformPackageName
+  try {
+    platformPackageName = resolvePackageName()
+  } catch {
+    return false
+  }
+
+  const platformVersion = packageJson.optionalDependencies && packageJson.optionalDependencies[platformPackageName]
+  const installSpec = platformVersion ? `${platformPackageName}@${platformVersion}` : platformPackageName
+  const npmExecutable = process.platform === "win32" ? "npm.cmd" : "npm"
+
+  console.log(`[codegenie] Platform package ${platformPackageName} not found, attempting to install...`)
+  try {
+    execFileSync(npmExecutable, ["install", "-g", installSpec], {
+      stdio: "inherit",
+      timeout: 120000,
+    })
+    return true
+  } catch (err) {
+    console.warn(`[codegenie] Failed to auto-install ${installSpec}: ${err && err.message ? err.message : String(err)}`)
+    return false
+  }
+}
+
+function runPostInstall() {
+  let resolved
+  try {
+    resolved = resolveBinary()
+  } catch (firstError) {
+    const attempted = tryInstallPlatformPackage()
+    if (!attempted) {
+      const message = firstError && firstError.message ? firstError.message : String(firstError)
+      console.warn("[codegenie] npm install completed, but platform binary verification will be deferred to first launch.")
+      console.warn(message)
+      return
+    }
+    try {
+      resolved = resolveBinary()
+    } catch (retryError) {
+      const message = retryError && retryError.message ? retryError.message : String(retryError)
+      console.warn("[codegenie] npm install completed, but platform binary verification will be deferred to first launch.")
+      console.warn(message)
+      return
+    }
+  }
 
-try {
-  const resolved = resolveBinary()
   console.log("[codegenie] npm install complete. Global command \"codegenie\" is ready.")
   console.log(`[codegenie] Using platform package ${resolved.packageName}.`)
-  console.log("[codegenie] First launch will only extract kernel files to ~/.codegenie/kernel. No second self-install is required.")
-} catch (error) {
-  const message = error && error.message ? error.message : String(error)
-  console.warn("[codegenie] npm install completed, but platform binary verification will be deferred to first launch.")
-  console.warn(message)
+  console.log("[codegenie] Prewarming runtime assets during npm install...")
+  let result = prewarmBinary(resolved.binaryPath, resolved.platformDir)
+  if (result.error || (typeof result.status === "number" && result.status !== 0)) {
+    const reason = result.error ? result.error.message : `exit code ${result.status}`
+    console.warn(`[codegenie] Runtime prewarm attempt 1 failed (${reason}), retrying...`)
+    result = prewarmBinary(resolved.binaryPath, resolved.platformDir)
+  }
+  if (result.error) {
+    console.warn(`[codegenie] Runtime prewarm failed: ${result.error.message}`)
+  } else if (typeof result.status === "number" && result.status !== 0) {
+    console.warn(`[codegenie] Runtime prewarm exited with code ${result.status}. First launch will finish initialization.`)
+  } else {
+    console.log("[codegenie] Runtime assets are ready. First launch should be faster.")
+  }
+
+  if (process.platform === "win32" && process.env.CODEGENIE_SKIP_WARM_STARTUP !== "true") {
+    console.log("[codegenie] Finalizing hidden first-launch warmup...")
+    const startupWarm = warmStartupBinary(resolved.binaryPath, resolved.platformDir)
+    if (startupWarm.error) {
+      console.warn(`[codegenie] Hidden startup warmup failed: ${startupWarm.error.message}`)
+    } else if (typeof startupWarm.status === "number" && startupWarm.status !== 0) {
+      console.warn(`[codegenie] Hidden startup warmup exited with code ${startupWarm.status}. First visible launch may still be slower.`)
+    }
+  }
 }
+
+runPostInstall()

package/bin/uninstall.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const { cleanupAfterNpmUninstall } = require("../lib/cleanup.js")
+
+try {
+  const result = cleanupAfterNpmUninstall()
+  if (result.removed) {
+    console.log(`[codegenie] Removed runtime directory: ${result.rootDir}`)
+  } else if (result.reason === "package-mismatch") {
+    console.log(`[codegenie] Skip runtime cleanup because install context belongs to another npm package.`)
+  } else if (result.reason === "missing") {
+    console.log("[codegenie] Runtime directory already removed.")
+  } else if (result.reason === "remove-failed") {
+    const hint = result.error && result.error.message ? ` (${result.error.message})` : ""
+    console.warn(`[codegenie] Failed to remove runtime directory${hint}. Remove manually: ${result.rootDir}`)
+  }
+} catch (error) {
+  const message = error && error.message ? error.message : String(error)
+  console.warn(`[codegenie] Runtime cleanup during npm uninstall failed: ${message}`)
+}

package/lib/cleanup.js

@@ -0,0 +1,97 @@
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+
+function runtimePaths(homeDir = os.homedir()) {
+  const rootDir = path.join(homeDir, ".codegenie")
+  const binDir = path.join(rootDir, "bin")
+  return {
+    rootDir,
+    binDir,
+    binaryPath: path.join(binDir, process.platform === "win32" ? "codegenie.exe" : "codegenie"),
+    installContextPath: path.join(rootDir, "install-context.json"),
+  }
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null
+}
+
+function belongsToExpectedPackageFamily(actualPackageName, expectedPackageName) {
+  return actualPackageName === expectedPackageName || actualPackageName.startsWith(`${expectedPackageName}-`)
+}
+
+function readInstallContext(homeDir = os.homedir()) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(runtimePaths(homeDir).installContextPath, "utf-8"))
+    if (!isRecord(raw)) return null
+    if (raw.installSource !== "npm" && raw.installSource !== "standalone") return null
+    return {
+      installSource: raw.installSource,
+      npmPackageName:
+        typeof raw.npmPackageName === "string" && raw.npmPackageName.trim() ? raw.npmPackageName.trim() : null,
+    }
+  } catch {
+    return null
+  }
+}
+
+function removeWithRetry(targetPath, maxRetries = 2) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      fs.rmSync(targetPath, { recursive: true, force: true })
+      return { success: true, error: null }
+    } catch (err) {
+      const code = err && err.code
+      if ((code === "EBUSY" || code === "EPERM") && attempt < maxRetries) {
+        const delay = (attempt + 1) * 500
+        const end = Date.now() + delay
+        while (Date.now() < end) { /* busy wait */ }
+        continue
+      }
+      return { success: false, error: err }
+    }
+  }
+  return { success: false, error: null }
+}
+
+function cleanupAfterNpmUninstall(options = {}) {
+  const homeDir = options.homeDir || os.homedir()
+  const expectedPackageName =
+    options.expectedPackageName || process.env.CODEGENIE_NPM_PACKAGE || process.env.npm_package_name || null
+  const paths = runtimePaths(homeDir)
+  const context = readInstallContext(homeDir)
+
+  if (
+    context &&
+    expectedPackageName &&
+    context.npmPackageName &&
+    context.installSource === "npm" &&
+    !belongsToExpectedPackageFamily(context.npmPackageName, expectedPackageName)
+  ) {
+    return { removed: false, reason: "package-mismatch", rootDir: paths.rootDir }
+  }
+
+  if (!fs.existsSync(paths.rootDir)) {
+    return { removed: false, reason: "missing", rootDir: paths.rootDir }
+  }
+
+  const result = removeWithRetry(paths.rootDir)
+  if (!result.success) {
+    return {
+      removed: false,
+      reason: "remove-failed",
+      rootDir: paths.rootDir,
+      error: result.error,
+    }
+  }
+  return { removed: true, reason: "removed", rootDir: paths.rootDir }
+}
+
+module.exports = {
+  belongsToExpectedPackageFamily,
+  cleanupAfterNpmUninstall,
+  readInstallContext,
+  removeWithRetry,
+  runtimePaths,
+}

package/lib/launch.js

@@ -0,0 +1,18 @@
+const packageJson = require("../package.json")
+
+function buildLaunchEnv(resolvedPackageName, platformDir, baseEnv = process.env) {
+  const env = {
+    ...baseEnv,
+    CODEGENIE_INSTALL_SOURCE: "npm",
+    CODEGENIE_NPM_PACKAGE: packageJson.name,
+    CODEGENIE_NPM_PLATFORM_PACKAGE: resolvedPackageName,
+  }
+  if (platformDir) {
+    env.CODEGENIE_NPM_PLATFORM_DIR = platformDir
+  }
+  return env
+}
+
+module.exports = {
+  buildLaunchEnv,
+}

package/lib/prewarm.js

@@ -0,0 +1,78 @@
+const fs = require("fs")
+const os = require("os")
+const { spawnSync } = require("child_process")
+
+function buildPrewarmEnv(platformDir, baseEnv = process.env) {
+  const env = {
+    ...baseEnv,
+    CODEGENIE_PREPARE_ONLY: "true",
+    CODEGENIE_INSTALL_SOURCE: "npm",
+    CODEGENIE_NPM_PACKAGE:
+      baseEnv.CODEGENIE_NPM_PACKAGE || baseEnv.npm_package_name || "codegenie",
+  }
+  if (platformDir) {
+    env.CODEGENIE_NPM_PLATFORM_DIR = platformDir
+  }
+  return env
+}
+
+function prewarmBinary(binaryPath, platformDir, spawnImpl = spawnSync, baseEnv = process.env) {
+  return spawnImpl(binaryPath, [], {
+    stdio: "ignore",
+    timeout: 120000,
+    env: buildPrewarmEnv(platformDir, baseEnv),
+  })
+}
+
+function buildStartupWarmEnv(platformDir, baseEnv = process.env) {
+  const env = {
+    ...baseEnv,
+    CODEGENIE_WARM_STARTUP: "true",
+    CODEGENIE_WARM_STARTUP_TIMEOUT_MS: baseEnv.CODEGENIE_WARM_STARTUP_TIMEOUT_MS || "10000",
+    CODEGENIE_INSTALL_SOURCE: "npm",
+    CODEGENIE_NPM_PACKAGE:
+      baseEnv.CODEGENIE_NPM_PACKAGE || baseEnv.npm_package_name || "codegenie",
+    OPENCODE_DISABLE_AUTOUPDATE: "true",
+  }
+  if (platformDir) {
+    env.CODEGENIE_NPM_PLATFORM_DIR = platformDir
+  }
+  return env
+}
+
+function resolveWarmupCwd(baseEnv = process.env, existsImpl = fs.existsSync) {
+  const initCwd = typeof baseEnv.INIT_CWD === "string" ? baseEnv.INIT_CWD.trim() : ""
+  if (initCwd && existsImpl(initCwd)) {
+    return initCwd
+  }
+
+  const userProfile = typeof baseEnv.USERPROFILE === "string" ? baseEnv.USERPROFILE.trim() : ""
+  if (userProfile) {
+    return userProfile
+  }
+
+  const home = typeof baseEnv.HOME === "string" ? baseEnv.HOME.trim() : ""
+  if (home) {
+    return home
+  }
+
+  return os.homedir()
+}
+
+function warmStartupBinary(binaryPath, platformDir, spawnImpl = spawnSync, baseEnv = process.env, existsImpl = fs.existsSync) {
+  return spawnImpl(binaryPath, [], {
+    stdio: "ignore",
+    timeout: 20000,
+    windowsHide: true,
+    cwd: resolveWarmupCwd(baseEnv, existsImpl),
+    env: buildStartupWarmEnv(platformDir, baseEnv),
+  })
+}
+
+module.exports = {
+  buildPrewarmEnv,
+  buildStartupWarmEnv,
+  prewarmBinary,
+  resolveWarmupCwd,
+  warmStartupBinary,
+}

package/lib/resolve-binary.js

@@ -38,17 +38,25 @@ function resolvePackageName() {
   throw new Error(`Unsupported npm platform: ${process.platform}/${process.arch}${libcSuffix}`)
 }
 
+function resolvePlatformPackageDir(packageName) {
+  const packageJsonPath = require.resolve(`${packageName}/package.json`)
+  return path.dirname(packageJsonPath)
+}
+
 function resolveBinary() {
   const packageName = resolvePackageName()
-  let packageJsonPath = ""
+  let platformDir = ""
   try {
-    packageJsonPath = require.resolve(`${packageName}/package.json`)
+    platformDir = resolvePlatformPackageDir(packageName)
   } catch (error) {
-    const metaPackageName = process.env.npm_package_name || "codegenie"
+    const metaPackageName = (() => {
+      try { return require("../package.json").name } catch { return null }
+    })() || process.env.npm_package_name || "@hippox/codegenie"
     const hint = [
       `[codegenie] Failed to locate installed binary package for ${process.platform}/${process.arch}.`,
       `[codegenie] Expected package: ${packageName}`,
-      `[codegenie] Reinstall with \`npm install -g ${metaPackageName}\` or use the standalone binary for baseline / unsupported CPUs.`,
+      `[codegenie] Reinstall with \`npm install -g ${metaPackageName}\`.`,
+      `[codegenie] If your npm disables optionalDependencies, install \`${packageName}\` manually and retry.`,
     ].join("\n")
     const wrapped = new Error(hint)
     wrapped.cause = error
@@ -56,7 +64,7 @@ function resolveBinary() {
   }
 
   const binaryPath = path.join(
-    path.dirname(packageJsonPath),
+    platformDir,
     "bin",
     process.platform === "win32" ? "codegenie.exe" : "codegenie",
   )
@@ -67,11 +75,13 @@ function resolveBinary() {
   return {
     packageName,
     binaryPath,
+    platformDir,
   }
 }
 
 module.exports = {
   detectLibc,
   resolveBinary,
+  resolvePlatformPackageDir,
   resolvePackageName,
 }

package/lib/startup-hint.js

@@ -0,0 +1,31 @@
+const NON_INTERACTIVE_ARGS = new Set([
+  "--version", "-v", "--help", "-h",
+  "check-update", "upgrade", "rollback", "uninstall",
+  "login", "logout",
+])
+
+function isInteractiveLaunch(argv = []) {
+  if (argv.length === 0) return true
+  if (argv[0] === "run" || argv[0] === "--") return true
+  return false
+}
+
+function shouldPrintStartupHint(argv = [], options = {}) {
+  const env = options.env || process.env
+  const isTTY = options.isTTY ?? process.stderr.isTTY
+
+  if (!isTTY) return false
+  if (env.CODEGENIE_PREPARE_ONLY === "true" || env.CODEGENIE_WARM_STARTUP === "true") return false
+  if (argv.length > 0 && NON_INTERACTIVE_ARGS.has(argv[0])) return false
+  return isInteractiveLaunch(argv)
+}
+
+function startupHintText() {
+  return "\x1b[36m\x1b[1m  CodeGenie\x1b[0m\x1b[2m  Loading...\x1b[0m"
+}
+
+module.exports = {
+  isInteractiveLaunch,
+  shouldPrintStartupHint,
+  startupHintText,
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@hippox/codegenie",
-  "version": "3.11.2026",
+  "version": "3.13.2026",
   "private": false,
-  "description": "HarmonyOS AI 开发 CLI，binary-first 发布并通过 npm 分发平台二进制",
+  "description": "HarmonyOS AI 开发 CLI，通过 npm 分发平台二进制",
   "license": "MIT",
   "scripts": {
-    "postinstall": "node ./bin/postinstall.js"
+    "postinstall": "node ./bin/postinstall.js",
+    "preuninstall": "node ./bin/uninstall.js",
+    "uninstall": "node ./bin/uninstall.js",
+    "postuninstall": "node ./bin/uninstall.js"
   },
   "bin": {
     "codegenie": "bin/codegenie.js"
@@ -23,7 +26,9 @@
     "ai"
   ],
   "optionalDependencies": {
-    "@hippox/codegenie-win32-x64": "3.11.2026"
+    "@hippox/codegenie-darwin-arm64": "3.13.2026",
+    "@hippox/codegenie-darwin-x64": "3.13.2026",
+    "@hippox/codegenie-win32-x64": "3.13.2026"
   },
   "publishConfig": {
     "access": "public"

package/platform-map.json

@@ -1,3 +1,5 @@
 {
+  "darwin-arm64": "@hippox/codegenie-darwin-arm64",
+  "darwin-x64": "@hippox/codegenie-darwin-x64",
   "win32-x64": "@hippox/codegenie-win32-x64"
 }