flower-trellis 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flower-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,113 +1,130 @@
-# 🌸 flower-trellis
+# flower-trellis
 
-> 一条命令装好 [Trellis](https://docs.trytrellis.app/) 工程框架,并自动融合 **skill-garden** 的强化包。
+[![npm version](https://img.shields.io/npm/v/flower-trellis.svg)](https://www.npmjs.com/package/flower-trellis)
+[![node](https://img.shields.io/node/v/flower-trellis.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/flower-trellis.svg)](./LICENSE)
 
-## 这是什么
+> 一条命令装好 [Trellis](https://docs.trytrellis.app/) 工程框架,并自动融合 **skill-garden** 强化包。
 
-`flower-trellis` 是一个 Node CLI(npm 包),把原本要分两步做的事合并成一键完成:
+`flower-trellis` 是 Trellis 的 npm 封装 CLI,把原本要分两步的工作合并为一键完成:安装/升级 Trellis 本体,并在其上叠加 skill-garden 的强化包(一组 `trellis-*` 技能与 workflow override)。强化包以快照形式随包发布,安装过程**零网络依赖**。
 
-1. **装/升级 Trellis 本体** —— [trytrellis.app](https://docs.trytrellis.app/) 出品的 AI 编程工程框架,
-   把 specs / tasks / memory 持久化进你的仓库,让任意 AI 编程 Agent 都遵循你的工程规范。
-   底层调用官方 `@mindfoldhq/trellis` 的 `init` / `update`。
-2. **叠加强化包** —— 自动套用 skill-garden 的强化补充包
-   (按目标项目的 Trellis 版本智能选择 `old / 0.5 / 0.6` variant),
-   内含一组 `trellis-*` 技能与 workflow override。强化包随本包发布,安装零网络。
+底层调用官方 `@mindfoldhq/trellis` 的 `init` / `update`,并按目标项目的 Trellis 版本自动选择匹配的强化包变体(`old` / `0.5` / `0.6`)。
 
-> **命名由来**:取自 skill-garden 的「园艺」主题 —— trellis 是花园里供藤蔓攀爬的棚架,
-> `flower-trellis` 即「开满花的棚架」:框架装好、强化包到位,即开即用。
+> **命名由来**:`flower-` 是这一系列 AI 工程工具的统一前缀(flower 系列),`trellis` 表示本工具负责包装 Trellis 框架。
 
-## 用法
+## 安装
 
 ```bash
-# 交互安装:flower 平台菜单(默认勾 codex + claude)→ Trellis 原生模板/monorepo 菜单
-npx flower-trellis init -u your-name
+# 全局安装(推荐),之后可用 flower-trellis 或简写 ftl / ft
+npm i -g flower-trellis
 
-# 指定平台(透传 trellis,跳过平台菜单),例如只装 claude
-npx flower-trellis init -u your-name --claude
+# 升级到最新版
+npm i -g flower-trellis@latest
+```
 
-# 完全非交互(平台默认 codex + claude;模板用空白默认)
-npx flower-trellis init -u your-name -y
+也可**免安装**通过 `npx flower-trellis <命令>` 直接运行(每次执行拉取最新版,适合临时试用)。
 
-# 升级 Trellis 并按新版本重新套用强化包
-npx flower-trellis update
+**环境要求**:Node.js ≥ 18.17.0。
 
-# 卸载:移除 Trellis 本体并清理强化包残留
-npx flower-trellis uninstall
+## 用法
+
+```bash
+# 交互安装:平台多选菜单 → Trellis 原生模板/monorepo 菜单
+flower-trellis init -u <your-name>
 
-# 只装 Trellis 不叠加强化包 / 已有项目只重叠加
-npx flower-trellis init --no-enhance
-npx flower-trellis init --enhance-only
+# 指定平台,跳过平台菜单(透传给 trellis)
+flower-trellis init -u <your-name> --claude
 
-# 其它 trellis 子命令一律透传(面向未来,零维护)
-npx flower-trellis <任意 trellis 命令>
+# 完全非交互(平台默认 codex + claude)
+flower-trellis init -u <your-name> -y
+
+# 升级 Trellis 并按新版本重新叠加强化包
+flower-trellis update
+
+# 卸载:移除 Trellis 本体并清理强化包残留
+flower-trellis uninstall
 
 # 查看版本(flower-trellis 自身 + 捆绑的 Trellis)
-npx flower-trellis -v
+flower-trellis -v
 ```
 
-## 交互流程(`init`)
+> 已全局安装时可直接写 `flower-trellis`、`ftl` 或 `ft`(三者等价);未安装则在命令前加 `npx`。
 
-```
-🌸 FLOWER 品牌头部(ASCII logo + 👤 Developer)
-   ↓
-? 选择 AI 工具(flower 菜单,默认勾 Claude Code + Codex)
-   ↓
-? Select a spec template / monorepo 识别 …(Trellis 原生交互,原样保留)
-   ↓
-叠加 skill-garden 强化包 + codex 后处理 → 完成
-```
+### 命令
 
-全程**只有 flower 一个 banner**:Trellis 子进程在伪终端(node-pty)里运行,
-它原生的模板 / monorepo / 冲突等交互完整保留,而它重复打印的启动 banner / Developer 被过滤掉。
+| 命令 | 说明 |
+|------|------|
+| `init` | 安装 Trellis 并叠加强化包(默认命令,裸跑等同 `init`) |
+| `update` | 升级 Trellis,并按新版本重新叠加强化包 |
+| `uninstall` | 移除 Trellis 本体并清理强化包残留(支持 `-y` / `--dry-run`) |
+| `<其它命令>` | 原样透传给 Trellis,覆盖其现有及未来子命令 |
+| `-v` / `-h` | 打印版本 / 帮助 |
+
+### 选项
+
+| 选项 | 说明 |
+|------|------|
+| `--no-enhance` | 只安装 Trellis,不叠加强化包 |
+| `--enhance-only` | 跳过 Trellis,仅叠加强化包(用于已有项目) |
+| `--skills <a,b,...>` | 只安装指定技能(可省略 `trellis-` 前缀) |
+| `--variant <old\|0.5\|0.6>` | 强制指定强化包变体(默认按 `.trellis/.version` 自动选) |
+| `--target <dir>` | 目标目录(默认当前目录) |
+| `--no-update-check` | 本次跳过 flower-trellis 新版本检测(等价环境变量 `FLOWER_NO_UPDATE_CHECK=1`) |
 
-## 状态
+未指定平台时,交互模式会弹出多选菜单(默认勾选 Claude Code + Codex);也可直接传 `--claude` / `--codex` / `--cursor` 等指定,或用 `-y` 跳过菜单。其余未识别的 flag(如 `-u`、`-f`、`--template`)一律透传给 Trellis。
 
-✅ **可用** —— 核心功能已实现并端到端验证。当前捆绑 Trellis `0.6.0-beta.8`。
+### 自动版本检测
 
-## 功能
+运行 `init` / `update` 时,flower-trellis 会顺带检测**自身**在 npm 上是否有新版本:
 
-- [x] `init` / `update` / `uninstall`,其它 trellis 子命令兜底透传
-- [x] flower 品牌 banner(`init` 交互 + `update`)
-- [x] flower 平台多选菜单,默认勾 **codex + claude**;或 `-y` 用默认、传 `--claude/--codex/--cursor` 等指定
-- [x] 用 **node-pty** 在伪终端运行 trellis,完整保留其模板 / monorepo / 冲突等原生交互,同时过滤掉重复 banner / Developer
-- [x] 自动识别 Trellis 版本,选择匹配的强化包 variant(`old / 0.5 / 0.6`)
-- [x] 强化 skill 跟随平台铺设(claude→`.claude/skills`,codex/gemini 等→`.agents/skills`)
-- [x] codex 后处理:注释 `config.toml` 的 `[features.multi_agent_v2]`、补全 `hooks.json` 的 `SessionStart`
-- [x] workflow override 幂等注入(先清旧块再注入 + 备份 `.bak`)
-- [x] 升级时清理过期强化项(`0.5`/`old` → `0.6` 删除淘汰的 skill/command,基于 flower manifest,只删自己铺过的)
-- [x] `Ctrl+C` 安全中止(取消时不会继续叠加)
-- [x] `-v` 同时打印 flower-trellis 与捆绑 Trellis 版本
-- [x] 幂等执行:重复运行安全
+- **联网、尽力而为**:带 2.5s 超时,离线 / 超时 / 失败一律静默跳过,绝不阻断安装/升级主流程。
+- **发现新版**(交互终端):提示并询问是否立即升级;同意则执行 `npm i -g flower-trellis@latest`,成功后请按提示重新运行命令(升级后强化包随新版更新,可再跑一次 `ft update` 重新叠加)。
+- **非交互**(`-y` 或非 TTY):仅打印一行升级提示,不弹确认、不阻塞。
+- **跳过检测**:经 `npx` 运行(本就是最新版)、或显式 `--no-update-check` / `FLOWER_NO_UPDATE_CHECK=1` 时不检测。
 
-## 强化包与更新机制
+## 工作原理
 
-强化包以**快照**形式打包在本仓库 `enhancements/`(由 `npm run sync` 从 skill-garden 同步),随 npm 发布,安装零网络。因此:
+`init` 的执行流程:
 
-- **Trellis 本体**:`update` 实时升级(trellis 自己拉最新)。
-- **强化包**:用当前安装的 flower-trellis 版本里的那份快照。要跟上 skill-garden 后续迭代,流程为:
-  `skill-garden 改动 → npm run sync + 发新版 → npm i -g flower-trellis@latest → flower-trellis update`。
+```
+flower banner → 平台多选菜单 → Trellis 原生交互(模板 / monorepo / 冲突)→ 叠加强化包 → codex 后处理
+```
 
-**重复安装 / 升级的正确性**(已实测,不会出现重复块或残留):
+- **统一品牌头部**:Trellis 子进程在伪终端(`node-pty`)中运行,其原生的模板 / monorepo / 冲突等交互完整保留,但重复打印的启动 banner 被过滤,全程只呈现一个 flower banner。
+- **按平台铺设技能**:Claude 铺到 `.claude/skills`,Codex / Gemini 等铺到 `.agents/skills`;并对 codex 做后处理(注释 `config.toml` 的 `[features.multi_agent_v2]`、补全 `hooks.json` 的 `SessionStart`)。
+- **幂等执行**:`workflow.md` 注入前先按 `BEGIN/END` 标记清除旧块再重注入(块数恒定,不会翻倍,首次注入前备份 `.bak`);技能文件覆盖式铺设,并通过 `.trellis/.flower-manifest.json` 记录已铺路径,升级时删除已淘汰项。
+- **安全中止**:`Ctrl+C` 取消后不会继续叠加。
 
-1. **skill 文件**:覆盖式铺设 + `.trellis/.flower-manifest.json` 记录上次铺过的路径,删除本次不再包含的项。
-2. **`workflow.md`**:每次注入前先 strip 掉所有旧的 skill-garden 块(按 `BEGIN/END` 标记整段删),再重注入 —— 块数恒定、绝不翻倍;首次注入前备份 `.bak`。
-3. **升级清理**:跨 variant / 跨快照版本删除淘汰的 skill / command。
+## 强化包与更新
 
-> ⚠️ **维护约束**:`workflow.md` 的 strip 依赖 `src/lib/workflow-inject.js` 里硬编码的 sentinel 名单。改现有块的**内容**无需动名单;但 skill-garden **新增一种 workflow 块类型**(新的 `BEGIN/END` 名)时,必须同步更新该名单,否则旧块清不掉。
+强化包以**快照**形式打包在 `enhancements/`(由 `npm run sync` 从 skill-garden 同步),随 npm 发布。因此两者更新节奏不同:
+
+- **Trellis 本体**:`update` 实时升级(由 Trellis 自身拉取最新)。
+- **强化包**:使用当前安装版本内置的快照。要跟进 skill-garden 的迭代,需升级 flower-trellis 本身:
+
+  ```bash
+  npm i -g flower-trellis@latest && flower-trellis update
+  ```
 
 ## 开发
 
 ```bash
-npm install                 # 安装依赖
-npm run sync                # 从 skill-garden 同步强化包快照到 enhancements/
-node bin/flower-trellis.js init -u you --target /某测试目录   # 本地试跑(勿在本仓库根直接 init)
+npm install                                    # 安装依赖
+npm run sync                                   # 从 skill-garden 同步强化包快照到 enhancements/
+node bin/flower-trellis.js init -u you --target /tmp/test-project   # 本地试跑(勿在本仓库根直接 init)
 ```
 
-运行时依赖:`@mindfoldhq/trellis`(捆绑的 Trellis 本体)、`node-pty`(伪终端,保留 trellis 交互)、`inquirer`(平台菜单)、`figlet` + `chalk`(banner)。
+修改强化包后务必重新 `npm run sync`,再发布新版本。
+
+> **维护约束**:`workflow.md` 的旧块清理依赖 `src/lib/workflow-inject.js` 中硬编码的 sentinel 名单。修改现有块的内容无需改动名单;但当 skill-garden **新增一种 workflow 块类型**(新的 `BEGIN/END` 名)时,必须同步更新该名单,否则旧块无法被清除。
 
 ## 相关项目
 
 | 项目 | 作用 |
 |------|------|
-| [Trellis](https://docs.trytrellis.app/)(`@mindfoldhq/trellis`) | AI 编程工程框架本体,本包作为 wrapper 调用其 `init`/`update`/`uninstall` 等 |
-| skill-garden | 强化补充包的来源(`.trellis/` 下 `old/0.5/0.6` 各 variant) |
+| [Trellis](https://docs.trytrellis.app/)(`@mindfoldhq/trellis`) | AI 编程工程框架本体,本包作为 wrapper 调用其 `init` / `update` / `uninstall` |
+| skill-garden | 强化包来源,提供 `old` / `0.5` / `0.6` 各变体 |
+
+## 许可证
+
+[MIT](./LICENSE)

package/enhancements/0.6/overrides/workflow-states/no_task.md

@@ -3,4 +3,6 @@ HIGHEST PRIORITY SKILL-GARDEN STATE GUARD (no_task):
 Creating/resuming a task is not implementation permission.
 After PRD ready and task started, next implementation action = `trellis-route(implement)`.
 If no active task exists, scan `.trellis/tasks/*/task.json` once per session for in-progress tasks with `last_push_snapshot`; surface completed_steps + next_step and suggest rebinding the active task before resuming.
+Do NOT use the harness built-in plan mode (`EnterPlanMode` / `ExitPlanMode`) as a substitute for this gate. Planning is Trellis-only: classify the turn, ask for task-creation consent, then `trellis-brainstorm` for complex work.
+If the turn is a meta edit to Trellis itself (Trellis tracking would be overkill), say so and ask to skip Trellis — never silently swap built-in plan mode in for the consent gate.
 <!-- END skill-garden workflow-state no_task v0.6 -->

package/enhancements/0.6/overrides/workflow.md

@@ -29,18 +29,20 @@ Check routing has no 4h preference file. Before `trellis-check`, `trellis-check-
 
 #### Finish-work Bookkeeping Guard
 
-`session_auto_commit` only controls script-managed bookkeeping commits for Trellis task archives and workspace journals. It does not disable Phase 3.4 code-work commits that the user explicitly confirms.
+`session_auto_commit` governs ONLY the script-managed bookkeeping commits that `task.py archive` and `add_session.py` make for their own files (`.trellis/tasks/**` archive moves and `.trellis/workspace/**` journal/index). It is NOT a global auto-commit switch, and it has NO authority over code commits.
 
-If `.trellis/config.yaml` contains `session_auto_commit: false`, finish-work must treat archive and journal writes as disk-only bookkeeping:
+Code commits always belong to Phase 3.4: the agent drafts the batched commit plan and commits only after the user confirms — in EVERY case, whether `session_auto_commit` is `true` or `false`. Never treat `session_auto_commit: true` as permission to auto-commit code, to skip the Phase 3.4 confirmation prompt, or to commit any path outside the two scripts' own bookkeeping files. The two are independent: this switch never decides whether code is committed, and it never decides whether to ask first.
+
+When `session_auto_commit: true` (the default): `task.py archive` produces a `chore(task): archive ...` commit and `add_session.py` produces a `chore: record journal` commit, each touching only its own bookkeeping files. Code stays dirty for the Phase 3.4 plan.
+
+When `.trellis/config.yaml` sets `session_auto_commit: false`, finish-work must treat archive and journal writes as disk-only bookkeeping:
 
 - Running `python3 ./.trellis/scripts/task.py archive <task>` may move task files, but must not be described as producing a `chore(task): archive ...` commit.
 - Running `python3 ./.trellis/scripts/add_session.py ...` may write workspace journal/index files, but must not be described as producing a `chore: record journal` commit.
 - Do not run a compensating `git add` / `git commit` for `.trellis/tasks/**` or `.trellis/workspace/**` just because those scripts skipped auto-commit.
 - Report the resulting `.trellis/tasks/**` and `.trellis/workspace/**` dirty paths to the user as bookkeeping changes for manual review.
 
-Phase 3.4 code-work commits are unchanged. If code files from the task are dirty, the agent may still present the normal one-shot commit plan and commit only after the user confirms.
-
-This guard only prevents archive/journal bookkeeping commits from being forced when `session_auto_commit: false`.
+This guard scopes `session_auto_commit` to the two bookkeeping commits above; Phase 3.4 code-work commits stay confirmation-gated regardless of its value.
 
 #### Push Progress Recovery / Snapshot
 

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-06-08T12:58:29.928Z",
+  "syncedAt": "2026-06-08T16:26:44.336Z",
   "syncedFrom": "/root/project/skill-garden/.trellis",
-  "sourceCommit": "824727cb279202c65bb653529fc84f5e135c25e2",
+  "sourceCommit": "1dcf26869e7c90be0777ebe3448501f340e05b45",
   "variants": {
     "old": {
       "claudeSkills": [],

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "flower-trellis",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
     "flower-trellis": "./bin/flower-trellis.js",
-    "ftl": "./bin/flower-trellis.js"
+    "ftl": "./bin/flower-trellis.js",
+    "ft": "./bin/flower-trellis.js"
   },
   "engines": {
     "node": ">=18.17.0"

package/src/cli.js

@@ -42,6 +42,10 @@ flower 自有 flag:
   --skills <a,b,...>       只装指定技能(支持去 trellis- 前缀匹配)
   --variant <old|0.5|0.6>  强制强化包变体(默认按 .trellis/.version 自动选)
   --target <dir>           目标目录(默认当前目录)
+  --no-update-check        本次跳过 flower-trellis 新版本检测(等价 FLOWER_NO_UPDATE_CHECK=1)
+
+命令别名:flower-trellis 可简写为 ftl 或 ft(三者完全等价)。
+init / update 启动时会顺带检测 flower-trellis 自身是否有新版(联网、带超时,失败静默)。
 
 平台选择:未指定平台时,交互模式会弹出多选菜单(默认勾 Claude Code + Codex);
 也可直接传 --claude / --codex / --cursor 等指定,或用 -y 跳过菜单(默认 codex + claude)。
@@ -55,6 +59,7 @@ function parse(argv) {
   let enhanceOnly = false;
   let variant = null;
   let target = process.cwd();
+  let updateCheck = true;
   const skills = [];
   const passthrough = [];
 
@@ -83,6 +88,9 @@ function parse(argv) {
       case "--target":
         target = path.resolve(argv[++i] || ".");
         break;
+      case "--no-update-check":
+        updateCheck = false;
+        break;
       default:
         passthrough.push(a);
     }
@@ -97,6 +105,7 @@ function parse(argv) {
       enhanceOnly,
       skills,
       variant,
+      updateCheck,
     },
   };
 }

package/src/commands/init.js

@@ -3,6 +3,7 @@ import { runTrellisPty } from "../lib/trellis-runner.js";
 import { applyEnhancements } from "../lib/apply-enhancements.js";
 import { pickPlatforms } from "../lib/pick-platforms.js";
 import { printBanner, getDeveloper } from "../lib/banner.js";
+import { checkForUpdate } from "../lib/update-check.js";
 import { PLATFORM_FLAGS } from "../constants.js";
 
 /**
@@ -32,6 +33,10 @@ export async function init(ctx) {
     printBanner(getDeveloper(passthrough, target));
   }
 
+  // 主操作前尽力而为地检测 flower-trellis 自身新版本(失败静默;用户确认升级成功会直接退出)
+  // 放在平台菜单之前:若用户选择升级,不必先让他挑完平台再退出做无用功
+  await checkForUpdate(ctx, "init");
+
   if (!hasPlatform) {
     if (nonInteractive) {
       passthrough.push("--codex", "--claude");

package/src/commands/update.js

@@ -1,6 +1,7 @@
 import { runTrellisPty } from "../lib/trellis-runner.js";
 import { applyEnhancements } from "../lib/apply-enhancements.js";
 import { printBanner, getDeveloper } from "../lib/banner.js";
+import { checkForUpdate } from "../lib/update-check.js";
 
 /**
  * flower-trellis update:驱动 `trellis update`,随后按(可能已升级的)版本重新叠加强化包。
@@ -17,6 +18,9 @@ export async function update(ctx) {
 
   printBanner(getDeveloper(ctx.passthrough, target));
 
+  // 主操作前尽力而为地检测 flower-trellis 自身新版本(失败静默;用户确认升级成功会直接退出)
+  await checkForUpdate(ctx, "update");
+
   if (!ctx.enhanceOnly) {
     const code = await runTrellisPty(["update", ...ctx.passthrough], target, {
       stripBanner: true,

package/src/constants.js

@@ -47,4 +47,5 @@ export const OWN_FLAGS = {
   "--skills": true,
   "--variant": true,
   "--target": true,
+  "--no-update-check": false,
 };

package/src/lib/update-check.js

@@ -0,0 +1,168 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import inquirer from "inquirer";
+import chalk from "chalk";
+import { flowerVersion } from "./versions.js";
+
+/**
+ * 版本自动检测 —— 在 init / update 启动时尽力而为地比对 npm 上 flower-trellis 自身的
+ * 最新版本,发现新版时提示用户并(交互场景下)询问是否立即升级。
+ *
+ * 设计基调与本项目一致:**绝不阻断主流程**。网络探测带超时,离线/超时/失败一律静默跳过;
+ * 仅在「全局直跑 + 有新版」时才打扰用户。详见 design.md / research/version-check-conventions.md。
+ */
+
+/** npm registry 根地址。 */
+const REGISTRY = "https://registry.npmjs.org";
+/** 待检测的包名(即本包)。 */
+const PKG = "flower-trellis";
+/** 网络探测超时(毫秒)—— init/update 是重操作,2.5s 探测可接受且不显著影响体感。 */
+const TIMEOUT_MS = 2500;
+
+/**
+ * 取 npm 上 flower-trellis 的 latest 版本号;任何失败(离线/超时/非 200/解析异常)一律
+ * 返回 null —— 调用方据此「拿不到就当没这回事」继续主流程。
+ *
+ * 用 AbortController 给内置 fetch 加超时,finally 清除定时器防句柄泄漏。
+ * @returns {Promise<string|null>} latest 版本号,或失败时 null
+ */
+export async function fetchLatestVersion() {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${REGISTRY}/${PKG}/latest`, {
+      signal: ac.signal,
+      headers: { Accept: "application/json" },
+    });
+    if (!res.ok) return null; // 非 200(404/5xx 等)→ 静默跳过
+    const json = await res.json();
+    return typeof json.version === "string" ? json.version : null;
+  } catch {
+    return null; // AbortError(超时)/ fetch failed(离线)/ JSON 解析失败 → 静默
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 比较两个版本号,返回 1 / 0 / -1(a 比 b 新 / 相同 / 旧)。
+ *
+ * 只比较 major.minor.patch 三段数值;预发布后缀(-beta.x 等)在拆分前剥除。
+ * 之所以不引 semver 库:比较对象是 npm `latest` dist-tag(按语义永远指向稳定发布),
+ * 天然不含预发布优先级排序问题。与 src/lib/variant.js「剥 -beta.x 再比数值」的先例一致。
+ * @param {string} a 版本号 A
+ * @param {string} b 版本号 B
+ * @returns {-1|0|1}
+ */
+export function compareVersions(a, b) {
+  const norm = (v) =>
+    String(v)
+      .split("-")[0]
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+  const [a1, a2, a3] = norm(a);
+  const [b1, b2, b3] = norm(b);
+  if (a1 !== b1) return a1 > b1 ? 1 : -1;
+  if (a2 !== b2) return a2 > b2 ? 1 : -1;
+  if (a3 !== b3) return a3 > b3 ? 1 : -1;
+  return 0;
+}
+
+/**
+ * 判断当前是否经 npx 执行。
+ *
+ * 经 npx 跑的永远是临时拉取的最新版,检测无意义,应跳过。最可靠的信号是执行路径里含
+ * npx 缓存目录标记 `_npx`(`~/.npm/_npx/<hash>/...`,跨平台一致);辅以 `npm_command==='exec'`
+ * (`npm exec` / npx)。全局安装直跑(flower-trellis / ftl / ft)时两者皆否。
+ * @returns {boolean}
+ */
+export function isRunningViaNpx() {
+  try {
+    const selfPath = fileURLToPath(import.meta.url);
+    if (selfPath.includes("_npx")) return true;
+  } catch {
+    // 路径解析失败不应影响主流程;退而判 npm_command
+  }
+  return process.env.npm_command === "exec";
+}
+
+/**
+ * 检测 flower-trellis 自身是否有新版本,并按场景提示/引导升级。在 init / update 的
+ * 品牌头部之后、主操作之前调用。
+ *
+ * 短路条件(任一命中即跳过,什么都不打印):关闭开关(`--no-update-check` 使
+ * `ctx.updateCheck===false`,或环境变量 `FLOWER_NO_UPDATE_CHECK` 非空)、经 npx 运行、
+ * 网络探测失败、已是最新或本地更高。
+ *
+ * 发现新版时的行为:
+ *  - 交互 TTY:打印通知 → inquirer 询问是否升级 → 同意则执行 `npm i -g flower-trellis@latest`;
+ *    成功后打印「请重新运行」并 **process.exit(0)**(不做 re-exec 自动重跑),失败则降级为
+ *    打印手动升级命令并继续主流程;拒绝则继续主流程。
+ *  - 非交互(`-y`/`--yes` 或非 TTY):仅打印通知 + 升级命令,不弹确认、不阻塞。
+ *
+ * @param {object} ctx cli.js parse() 产出的上下文(用到 updateCheck / passthrough)
+ * @param {string} commandLabel 当前命令名,用于「请重新运行 ft <command>」文案(如 "init"/"update")
+ * @returns {Promise<void>} 注意:用户确认升级且成功时本函数会直接退出进程,不返回
+ */
+export async function checkForUpdate(ctx, commandLabel) {
+  // 1. 关闭开关:显式 flag 或环境变量
+  if (ctx.updateCheck === false || process.env.FLOWER_NO_UPDATE_CHECK) return;
+  // 2. npx 本就是最新版,跳过(连通知都不打,避免误导)
+  if (isRunningViaNpx()) return;
+
+  // 3. 尽力而为取 latest;拿不到就静默退出
+  const latest = await fetchLatestVersion();
+  if (!latest) return;
+
+  // 4. 与本地版本比较;仅当 latest 严格更新时才打扰
+  const current = flowerVersion();
+  if (compareVersions(latest, current) !== 1) return;
+
+  // 5. 打印发现新版本通知(粉色品牌色,与 banner 一致)
+  console.log(
+    "\n🌸 " +
+      chalk.hex("#ff6fb5")(`发现 flower-trellis 新版本 ${chalk.bold(latest)}`) +
+      chalk.gray(`(当前 ${current})`),
+  );
+
+  // 6. 非交互(-y/--yes 或非 TTY):仅打印升级命令,不弹确认、不阻塞
+  const nonInteractive =
+    ctx.passthrough.includes("-y") ||
+    ctx.passthrough.includes("--yes") ||
+    !process.stdin.isTTY;
+  if (nonInteractive) {
+    console.log(`  · 升级:npm i -g ${PKG}@latest`);
+    console.log("  · 升级后请重跑 ft update,让新版强化包重新叠加到现有项目");
+    return;
+  }
+
+  // 7. 交互:询问是否升级
+  const { doUpgrade } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "doUpgrade",
+      message: `是否现在升级到 ${latest}?(升级后需重新运行命令)`,
+      default: true,
+    },
+  ]);
+  if (!doUpgrade) {
+    console.log("  · 已跳过升级");
+    return;
+  }
+
+  // 8. 执行全局升级。失败(含 EACCES 权限问题、npm 不存在)不自行提权,降级为打印手动命令
+  const res = spawnSync("npm", ["i", "-g", `${PKG}@latest`], {
+    stdio: "inherit",
+    shell: process.platform === "win32", // Windows 上 npm 实为 npm.cmd
+  });
+  if (res.status === 0) {
+    console.log(`\n  ✓ 已升级到 ${latest}`);
+    console.log(`  · 请重新运行 ft ${commandLabel} 以使用新版本`);
+    console.log("  · 强化包随版本更新,升级后可 ft update 重新叠加到现有项目");
+    // 当前进程内存里仍是旧代码,必须退出由用户重跑新版本(不做 re-exec,规避权限/平台/进程态坑)
+    process.exit(0);
+  } else {
+    console.log(`  · 自动升级失败,请手动运行:npm i -g ${PKG}@latest`);
+    // 升级未成功:以当前版本继续 init/update,不阻断
+  }
+}