@hippox/codegenie 1.2.15 → 3.11.2026-alpha.1

package/README.md

@@ -1,25 +1,49 @@
-# CodeGenie CLI
-
-`CodeGenie` 是面向 HarmonyOS 开发场景的 AI CLI。
-
-## 安装
-
-```bash
-npm install -g codegenie
-```
-
-安装完成后直接执行：
-
-```bash
-codegenie --version
-```
-
-## 平台说明
-
-- npm 安装默认提供主流 `Windows/macOS/Linux` 二进制包
-- `baseline` 兼容构建不会通过 npm 分发，老 CPU 请改用独立二进制发布件
-- `upgrade` 在 npm 安装场景下会提示或委托 `npm install -g codegenie@<tag>`，不会直接覆写 npm 全局目录
-
-## 发布说明
-
-仓库中的 `packages/npm/codegenie` 为元包模板。正式发布前请先运行仓库脚本生成 `dist/npm/` 下的 publishable 包，再按发布顺序上传各平台包和元包。
+# CodeGenie CLI
+
+`CodeGenie` 是面向 HarmonyOS 开发场景的 AI CLI。
+
+## 安装
+
+```bash
+npm install -g @hippox/codegenie
+```
+
+安装完成后即可直接执行：
+
+```bash
+codegenie --version
+```
+
+说明：
+
+- npm 安装会直接创建全局 `codegenie` 命令
+- npm 安装阶段会预热 runtime assets；Windows 还会额外隐藏预热一次默认启动路径，因此安装时间会略长，但首次可见启动会更快
+- 首次运行通常不再需要解包和安装依赖；首次进入某个工作区时，仍可能有少量项目级初始化
+- 首次运行不会再把二进制复制到 `~/.codegenie/bin`
+- npm 安装/升级会清理旧的 standalone 二进制和临时更新残留
+- `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`
+
+- `baseline` 兼容构建不会通过 npm 分发，老 CPU 请改用独立二进制发布件
+
+## 发布说明
+
+仓库中的 `packages/npm/codegenie` 为元包模板。正式发布前请先运行仓库脚本生成 `dist/npm/` 下的 publishable 包，再按发布顺序上传各平台包和元包。

package/bin/codegenie.js

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 
 const { spawnSync } = require("child_process")
+const { buildLaunchEnv } = require("../lib/launch.js")
 const { resolveBinary } = require("../lib/resolve-binary.js")
+const { shouldPrintStartupHint, startupHintText } = require("../lib/startup-hint.js")
 
 function main() {
+  if (shouldPrintStartupHint(process.argv.slice(2))) {
+    console.error(startupHintText())
+  }
+
   const resolved = resolveBinary()
   const result = spawnSync(resolved.binaryPath, process.argv.slice(2), {
     stdio: "inherit",
-    env: {
-      ...process.env,
-      CODEGENIE_INSTALL_SOURCE: "npm",
-      CODEGENIE_NPM_PACKAGE: resolved.packageName,
-    },
+    env: buildLaunchEnv(resolved.packageName, resolved.platformDir, process.env),
   })
 
   if (result.error) {

package/bin/postinstall.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const { resolveBinary } = require("../lib/resolve-binary.js")
+const { prewarmBinary, warmStartupBinary } = require("../lib/prewarm.js")
+
+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] 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") {
+    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.`)
+    }
+  }
+} 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)
+}

package/bin/uninstall.js

@@ -0,0 +1,19 @@
+#!/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 === "standalone-active") {
+    console.log("[codegenie] Skip runtime cleanup because standalone installation is still active.")
+  } else if (result.reason === "package-mismatch") {
+    console.log("[codegenie] Skip runtime cleanup because install context belongs to another npm package.")
+  } else if (result.reason === "standalone-binary-present") {
+    console.log("[codegenie] Skip runtime cleanup because standalone binary is still present.")
+  }
+} 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,76 @@
+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 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 && context.installSource === "standalone") {
+    return { removed: false, reason: "standalone-active", rootDir: paths.rootDir }
+  }
+
+  if (
+    context &&
+    expectedPackageName &&
+    context.npmPackageName &&
+    !belongsToExpectedPackageFamily(context.npmPackageName, expectedPackageName)
+  ) {
+    return { removed: false, reason: "package-mismatch", rootDir: paths.rootDir }
+  }
+
+  if (!context && fs.existsSync(paths.binaryPath)) {
+    return { removed: false, reason: "standalone-binary-present", rootDir: paths.rootDir }
+  }
+
+  if (!fs.existsSync(paths.rootDir)) {
+    return { removed: false, reason: "missing", rootDir: paths.rootDir }
+  }
+
+  fs.rmSync(paths.rootDir, { recursive: true, force: true })
+  return { removed: true, reason: "removed", rootDir: paths.rootDir }
+}
+
+module.exports = {
+  belongsToExpectedPackageFamily,
+  cleanupAfterNpmUninstall,
+  readInstallContext,
+  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,16 +38,22 @@ 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 hint = [
       `[codegenie] Failed to locate installed binary package for ${process.platform}/${process.arch}.`,
       `[codegenie] Expected package: ${packageName}`,
-      "[codegenie] Reinstall with `npm install -g codegenie` or use the standalone binary for baseline / unsupported CPUs.",
+      `[codegenie] Reinstall with \`npm install -g ${metaPackageName}\` or use the standalone binary for baseline / unsupported CPUs.`,
     ].join("\n")
     const wrapped = new Error(hint)
     wrapped.cause = error
@@ -55,7 +61,7 @@ function resolveBinary() {
   }
 
   const binaryPath = path.join(
-    path.dirname(packageJsonPath),
+    platformDir,
     "bin",
     process.platform === "win32" ? "codegenie.exe" : "codegenie",
   )
@@ -66,11 +72,13 @@ function resolveBinary() {
   return {
     packageName,
     binaryPath,
+    platformDir,
   }
 }
 
 module.exports = {
   detectLibc,
   resolveBinary,
+  resolvePlatformPackageDir,
   resolvePackageName,
 }

package/lib/startup-hint.js

@@ -0,0 +1,19 @@
+function shouldPrintStartupHint(argv = [], options = {}) {
+  const env = options.env || process.env
+  const platform = options.platform || process.platform
+  const isTTY = options.isTTY ?? process.stderr.isTTY
+
+  if (!isTTY) return false
+  if (platform !== "win32") return false
+  if (env.CODEGENIE_PREPARE_ONLY === "true" || env.CODEGENIE_WARM_STARTUP === "true") return false
+  return argv.length === 0
+}
+
+function startupHintText() {
+  return "[codegenie] Starting interface..."
+}
+
+module.exports = {
+  shouldPrintStartupHint,
+  startupHintText,
+}

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@hippox/codegenie",
-  "version": "1.2.15",
+  "version": "3.11.2026-alpha.1",
   "private": false,
   "description": "HarmonyOS AI 开发 CLI，binary-first 发布并通过 npm 分发平台二进制",
   "license": "MIT",
+  "scripts": {
+    "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"
   },
@@ -20,7 +26,7 @@
     "ai"
   ],
   "optionalDependencies": {
-    "@hippox/codegenie-win32-x64": "1.2.15"
+    "@hippox/codegenie-win32-x64": "3.11.2026-alpha.1"
   },
   "publishConfig": {
     "access": "public"