flower-trellis 0.2.3 → 0.2.5-beta.1

package/enhancements/0.6/overrides/workflow.md

@@ -6,7 +6,7 @@
 
 **Priority**: This hub overrides any conflicting Trellis workflow, skill, or command text for the scoped behaviors below.
 
-**Scope**: Phase 2.1 / 2.2 / 3.1 dispatch routing, Phase 3.4 code-commit/push via trellis-push, Phase 3.5 finish-work bookkeeping, and push-progress recovery / snapshot reminders. State blocks should keep only one short skill-garden sentinel per state; long-form rules live here.
+**Scope**: Phase 2.1 / 2.2 / 3.1 dispatch routing, post-check stop, Phase 3.4 code commit/push via trellis-push, explicit Phase 3.5 finish-work bookkeeping, and push-progress recovery. State blocks should keep only one short skill-garden sentinel per state; long-form rules live here.
 
 **Mechanical rule**: use this hub as the source of truth. Do not add separate top-level skill-garden override sections or multiple skill-garden sentinels inside the same `workflow-state:*` block.
 
@@ -14,28 +14,38 @@
 
 Before any implement/check agent or check skill runs from the main session, the immediately preceding routing decision must come from `trellis-route` or from the same numbered fallback choices shown in normal chat when the helper is unavailable.
 
-`trellis-route` returns 4 modes for `target=check` (check-all/check x inline/subagent) and 2 for `target=implement`. Step 1.7's recommendation is generated inside the skill and surfaced via Step 2's `AskUserQuestion`; that is the only prompt point.
+`trellis-route` may use the gitignored personal preference file `.trellis/.route-prefs.tmp` to skip repeated prompts. This file is developer-local state and must never be staged or committed.
+
+Personal route preferences are execution-mode preferences only, never authorization to start work; `trellis-route` may read them only after the workflow already permits the requested target.
+
+`trellis-route` returns 2 normal modes for `target=implement` (inline/subagent) and 2 normal modes for `target=check` (check-all inline/check-all subagent). Lightweight `trellis-check` is a hidden escape hatch only when the user explicitly asks for `light check` / `轻量检查`; it is not shown in normal check options.
 
 If the platform cannot call `AskUserQuestion` / `request_user_input`, ask the same numbered choices in normal chat and wait for the user's reply. Tool unavailability is not permission to record inline/subagent or to dispatch a sub-agent directly.
 
 Before invoking the skill, never:
 - write pre-questions ("ready to start? / shall I proceed?")
 - state "I lean towards X" or preview the inline/subagent options
-- surface Step 1.7 rationale ahead of time
+- surface route options ahead of time
 
 At phase boundaries, do not ask meta continuation questions such as "continue?", "what's next?", or "X or Y?" when the answer determines the next workflow phase. Invoke `trellis-route(implement|check)` first, or ask the same numbered route choices if the helper is unavailable.
 
-Check routing has no 4h preference file. Before `trellis-check`, `trellis-check-all`, or either check sub-agent, route every time so the user can choose check-all vs lightweight and inline vs subagent.
+If the user says "temporary override", "reselect", "use X this time", "clear route default", or equivalent, the personal preference file must not take priority. `trellis-route` must show the override options again and let the user choose whether the choice is one-time, saved as the new default, or clears the default.
 
-#### Code Commit Confirmation Gate
+For normal check routing, default to `trellis-check-all` paths. Do not route to lightweight `trellis-check` unless the user explicitly asks for the hidden light-check escape hatch.
+
+#### Post-Check Stop Gate
 
-Every code commit — and its push — belongs to Phase 3.4 and MUST go through `trellis-push`, mirroring how implement/check must go through `trellis-route`. From the main session the agent never runs bare `git commit` / `git push` on code to bypass it.
+After `trellis-check` or `trellis-check-all` finishes, stop and report the result. Do not run `/trellis:finish-work`, do not archive the task, and do not imply the task is ready to wrap up solely because checks passed.
+
+If checks pass, the next allowed workflow steps are Phase 3.3 `trellis-update-spec` and Phase 3.4 `trellis-push`/commit confirmation. `/trellis:finish-work` is explicit-only: run it only after Phase 3.4 is complete and the user asks to wrap up, archive, or finish the task.
+
+#### Code Commit Confirmation Gate
 
-`trellis-push` IS the confirmation mechanism: its Step 2.2 stages only an explicit, user-approved file list (never `git add -A` / `git add .`); its Step 2.3 shows the drafted commit message for approval. "Confirmed" means the user saw that concrete file list + message inside `trellis-push` and approved it. A preference-style choice does NOT count — e.g. an `AskUserQuestion` "split / single commit" option only picks a strategy, and an option label/description never substitutes for the real file-list + message display.
+Code commit/push belongs only to Phase 3.4 and must go through `trellis-push`; the main session must not run bare `git commit` / `git push` for code.
 
-For Phase 3.4 "commit now, push later", invoke `trellis-push` in commit-only mode (commit without pushing); the later push also goes through `trellis-push`.
+`trellis-push` confirmation must show both the exact file list to stage and the drafted commit message. Before the user approves that concrete list + message, do not `git add`, commit, or push; never use `git add -A` / `git add .`.
 
-This gate is independent of `session_auto_commit`: that switch never authorizes a code commit and never waives going through `trellis-push`. The only bare-`git` commits allowed are the two bookkeeping scripts below, which manage their own `.trellis/**` files.
+For "commit now, push later", use `trellis-push` commit-only mode; the later push still goes through `trellis-push`. `session_auto_commit` never authorizes code commits; it only affects bookkeeping commits below.
 
 #### Bookkeeping Auto-commit Scope
 

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-06-08T18:22:30.404Z",
+  "syncedAt": "2026-06-15T07:18:45.088Z",
   "syncedFrom": "vendor/skill-garden/.trellis",
-  "sourceCommit": "ec0ab7e2dd90b6cfdd86fb7a005610e245c36d40",
+  "sourceCommit": "cbe89cb482f53a2db7a21ba6dfaf8e0cf8d6af50",
   "variants": {
     "old": {
       "claudeSkills": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.2.3",
+  "version": "0.2.5-beta.1",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -12,10 +12,10 @@
     "node": ">=18.17.0"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
     "@mindfoldhq/trellis": "0.6.0-beta.8",
     "chalk": "^5.6.2",
     "figlet": "^1.11.0",
-    "inquirer": "^9.3.8",
     "node-pty": "^1.1.0"
   },
   "files": [

package/src/cli.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { flowerVersion, trellisVersion } from "./lib/versions.js";
 import { selectVariant } from "./lib/variant.js";
+import { readManifest } from "./lib/manifest.js";
 import { runTrellis } from "./lib/trellis-runner.js";
 
 /**
@@ -21,6 +22,10 @@ function printVersion(cwd) {
       const { version } = selectVariant(cwd);
       if (version) console.log(`project .trellis  ${version}`);
     }
+    // 项目里 flower 上次铺包时戳入的自身版本(来自 .flower-manifest.json);
+    // 与首行「当前工具版本」对比即可看出该项目是否需要重新 update。
+    const mf = readManifest(cwd);
+    if (mf && mf.flowerVersion) console.log(`project flower    ${mf.flowerVersion}`);
   } catch {
     // 忽略:版本读取失败不应影响 -v 输出
   }

package/src/lib/apply-enhancements.js

@@ -7,6 +7,7 @@ import { copySkills } from "./copy-skills.js";
 import { injectWorkflow } from "./workflow-inject.js";
 import { applyCodexTweaks } from "./codex-tweaks.js";
 import { readManifest, writeManifest } from "./manifest.js";
+import { flowerVersion } from "./versions.js";
 import { rmrf } from "./fs-utils.js";
 
 /** 清理升级后可能变空的强化目录(深 → 浅)。 */
@@ -101,7 +102,15 @@ export function applyEnhancements(target, opts = {}) {
         pruneEmptyDirs(target);
       }
     }
-    writeManifest(target, { variant, version, skills: installed, paths: newPaths });
+    // 写 manifest 时同时戳入 flower-trellis 自身版本(flowerVersion),与 version(项目 Trellis
+    // 版本)区分开:前者答「上次是哪个 flower 铺的包」,服务后续升级/维护判断。
+    writeManifest(target, {
+      flowerVersion: flowerVersion(),
+      variant,
+      version,
+      skills: installed,
+      paths: newPaths,
+    });
   }
 
   // workflow 注入:无过滤名(全装)或显式指定 workflow-enhancement/finish-work-enhancement 时执行

package/src/lib/pick-platforms.js

@@ -1,4 +1,4 @@
-import inquirer from "inquirer";
+import { checkbox } from "@inquirer/prompts";
 
 /**
  * 平台多选清单 —— flower 自己的平台选择菜单。
@@ -39,19 +39,21 @@ const PLATFORMS = [
  */
 export async function pickPlatforms() {
   if (!process.stdin.isTTY) return ["--codex", "--claude"];
-  const { tools } = await inquirer.prompt([
-    {
-      type: "checkbox",
-      name: "tools",
-      message:
-        "选择要配置的 AI 工具(空格勾选 / 回车确认,默认已勾 Claude Code + Codex):",
-      choices: PLATFORMS.map((p) => ({
-        name: p.name,
-        value: p.value,
-        checked: !!p.checked,
-      })),
-      loop: false,
-    },
-  ]);
+  // 用 @inquirer/checkbox(现代 @inquirer/core 增量重绘内核)替代经典 inquirer。
+  // 为什么换:经典 inquirer 每次重绘都「整块清屏 → 整块重写」,在 WSL2 / ConPTY 终端下
+  // 清空与重画之间有一帧空白,上下切换平台时肉眼可见闪屏;新内核按差异增量重绘可消闪。
+  // pageSize 取平台总数,一屏展示全部、避免滚动带来的二次重绘;loop:false 保持首尾不循环。
+  // 返回值即选中的 value 数组(["--claude","--codex", ...]),对调用方契约不变。
+  const tools = await checkbox({
+    message:
+      "选择要配置的 AI 工具(空格勾选 / 回车确认,默认已勾 Claude Code + Codex):",
+    choices: PLATFORMS.map((p) => ({
+      name: p.name,
+      value: p.value,
+      checked: !!p.checked,
+    })),
+    loop: false,
+    pageSize: PLATFORMS.length,
+  });
   return tools;
 }

package/src/lib/update-check.js

@@ -1,15 +1,15 @@
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import inquirer from "inquirer";
+import { confirm } from "@inquirer/prompts";
 import chalk from "chalk";
 import { flowerVersion } from "./versions.js";
 
 /**
  * 版本自动检测 —— 在 init / update 启动时尽力而为地比对 npm 上 flower-trellis 自身的
- * 最新版本,发现新版时提示用户并(交互场景下)询问是否立即升级。
+ * 可用版本,发现新版时提示用户并(交互场景下)询问是否立即升级。
  *
  * 设计基调与本项目一致:**绝不阻断主流程**。网络探测带超时,离线/超时/失败一律静默跳过;
- * 仅在「全局直跑 + 有新版」时才打扰用户。详见 design.md / research/version-check-conventions.md。
+ * 仅在「全局直跑 + 有新版」时才打扰用户。稳定版只跟 latest;预发布版同时看 latest / beta。
  */
 
 /** npm registry 根地址。 */
@@ -20,23 +20,26 @@ const PKG = "flower-trellis";
 const TIMEOUT_MS = 2500;
 
 /**
- * 取 npm 上 flower-trellis 的 latest 版本号;任何失败(离线/超时/非 200/解析异常)一律
+ * 取 npm 上 flower-trellis 的 dist-tags;任何失败(离线/超时/非 200/解析异常)一律
  * 返回 null —— 调用方据此「拿不到就当没这回事」继续主流程。
  *
  * 用 AbortController 给内置 fetch 加超时,finally 清除定时器防句柄泄漏。
- * @returns {Promise<string|null>} latest 版本号,或失败时 null
+ * @returns {Promise<{latest:string|null,beta:string|null}|null>} 可用 dist-tags,或失败时 null
  */
-export async function fetchLatestVersion() {
+export async function fetchPackageDistTags() {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
   try {
-    const res = await fetch(`${REGISTRY}/${PKG}/latest`, {
+    const res = await fetch(`${REGISTRY}/${PKG}`, {
       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;
+    const tags = json && typeof json === "object" ? json["dist-tags"] : null;
+    const latest = typeof tags?.latest === "string" ? tags.latest : null;
+    const beta = typeof tags?.beta === "string" ? tags.beta : null;
+    return latest || beta ? { latest, beta } : null;
   } catch {
     return null; // AbortError(超时)/ fetch failed(离线)/ JSON 解析失败 → 静默
   } finally {
@@ -44,28 +47,130 @@ export async function fetchLatestVersion() {
   }
 }
 
+/**
+ * 取 npm 上 flower-trellis 的 latest 版本号。
+ *
+ * 保留这个导出是为了兼容已有调用方;新逻辑应优先使用 `fetchPackageDistTags()`。
+ * @returns {Promise<string|null>} latest 版本号,或失败时 null
+ */
+export async function fetchLatestVersion() {
+  const tags = await fetchPackageDistTags();
+  return tags?.latest ?? null;
+}
+
+/**
+ * 解析项目需要的轻量 semver 版本号。
+ *
+ * @param {string} version 版本号
+ * @returns {{major:number,minor:number,patch:number,prerelease:string[]}|null} 解析结果
+ */
+function parseVersion(version) {
+  const match = String(version || "")
+    .trim()
+    .replace(/^v/, "")
+    .match(/^(\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(".") : [],
+  };
+}
+
+/**
+ * 判断版本号是否为 prerelease。
+ *
+ * @param {string} version 版本号
+ * @returns {boolean}
+ */
+export function isPrerelease(version) {
+  const parsed = parseVersion(version);
+  return Boolean(parsed && parsed.prerelease.length);
+}
+
+/**
+ * 比较 prerelease 标识符数组。
+ *
+ * 同一 base 下,稳定版高于 prerelease;相同 label(如 beta.1 → beta.2)按数值递增比较。
+ * 不同 label 之间不做主观排序,返回 0 以避免把 alpha/rc/beta 的跨线比较误判成升级。
+ *
+ * @param {string[]} aParts A prerelease 标识符
+ * @param {string[]} bParts B prerelease 标识符
+ * @returns {-1|0|1}
+ */
+function comparePrerelease(aParts, bParts) {
+  if (!aParts.length && !bParts.length) return 0;
+  if (!aParts.length) return 1;
+  if (!bParts.length) return -1;
+  if (aParts[0] !== bParts[0]) return 0;
+
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i++) {
+    const a = aParts[i];
+    const b = bParts[i];
+    if (a === undefined) return -1;
+    if (b === undefined) return 1;
+    if (a === b) continue;
+
+    const aNum = /^\d+$/.test(a);
+    const bNum = /^\d+$/.test(b);
+    if (aNum && bNum) {
+      const delta = Number(a) - Number(b);
+      if (delta !== 0) return delta > 0 ? 1 : -1;
+      continue;
+    }
+    if (aNum !== bNum) return aNum ? -1 : 1;
+    return a > b ? 1 : -1;
+  }
+  return 0;
+}
+
 /**
  * 比较两个版本号,返回 1 / 0 / -1(a 比 b 新 / 相同 / 旧)。
  *
- * 只比较 major.minor.patch 三段数值;预发布后缀(-beta.x 等)在拆分前剥除。
- * 之所以不引 semver 库:比较对象是 npm `latest` dist-tag(按语义永远指向稳定发布),
- * 天然不含预发布优先级排序问题。与 src/lib/variant.js「剥 -beta.x 再比数值」的先例一致。
+ * 支持 `major.minor.patch` 与项目 beta 通道使用的 `major.minor.patch-beta.n`。
+ * 不引 `semver` 依赖,因为这里仅服务启动时的轻量升级提示,失败/不认识时宁可不提示。
  * @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;
+  const av = parseVersion(a);
+  const bv = parseVersion(b);
+  if (!av || !bv) return 0;
+
+  for (const key of ["major", "minor", "patch"]) {
+    if (av[key] !== bv[key]) return av[key] > bv[key] ? 1 : -1;
+  }
+  return comparePrerelease(av.prerelease, bv.prerelease);
+}
+
+/**
+ * 根据当前版本和 npm dist-tags 生成升级推荐。
+ *
+ * 稳定版只跟随稳定形态的 latest,避免把稳定用户引导到预发布通道;预发布版同时看
+ * 稳定形态的 latest / beta,且 latest 高于当前版本时优先推荐 latest,用于 beta 线被
+ * 稳定版追上后的回归稳定。
+ *
+ * @param {string} current 当前安装的 flower-trellis 版本
+ * @param {{latest?:string|null,beta?:string|null}|null} tags npm dist-tags
+ * @returns {{version:string,tag:"latest"|"beta",command:string}|null} 升级推荐
+ */
+export function getUpdateRecommendation(current, tags) {
+  if (!current || !tags) return null;
+  const currentIsPrerelease = isPrerelease(current);
+  const latest = typeof tags.latest === "string" ? tags.latest : null;
+  const beta = typeof tags.beta === "string" ? tags.beta : null;
+  const latestIsStable = latest && !isPrerelease(latest);
+
+  if (latestIsStable && compareVersions(latest, current) === 1) {
+    return { version: latest, tag: "latest", command: `npm i -g ${PKG}@latest` };
+  }
+  if (currentIsPrerelease && beta && compareVersions(beta, current) === 1) {
+    return { version: beta, tag: "beta", command: `npm i -g ${PKG}@beta` };
+  }
+  return null;
 }
 
 /**
@@ -92,10 +197,10 @@ export function isRunningViaNpx() {
  *
  * 短路条件(任一命中即跳过,什么都不打印):关闭开关(`--no-update-check` 使
  * `ctx.updateCheck===false`,或环境变量 `FLOWER_NO_UPDATE_CHECK` 非空)、经 npx 运行、
- * 网络探测失败、已是最新或本地更高。
+ * 网络探测失败、无升级推荐。
  *
  * 发现新版时的行为:
- *  - 交互 TTY:打印通知 → inquirer 询问是否升级 → 同意则执行 `npm i -g flower-trellis@latest`;
+ *  - 交互 TTY:打印通知 → confirm 询问是否升级 → 同意则执行推荐的 npm install 命令;
  *    成功后打印「请重新运行」并 **process.exit(0)**(不做 re-exec 自动重跑),失败则降级为
  *    打印手动升级命令并继续主流程;拒绝则继续主流程。
  *  - 非交互(`-y`/`--yes` 或非 TTY):仅打印通知 + 升级命令,不弹确认、不阻塞。
@@ -110,19 +215,20 @@ export async function checkForUpdate(ctx, commandLabel) {
   // 2. npx 本就是最新版,跳过(连通知都不打,避免误导)
   if (isRunningViaNpx()) return;
 
-  // 3. 尽力而为取 latest;拿不到就静默退出
-  const latest = await fetchLatestVersion();
-  if (!latest) return;
+  // 3. 尽力而为取 dist-tags;拿不到就静默退出
+  const tags = await fetchPackageDistTags();
+  if (!tags) return;
 
-  // 4. 与本地版本比较;仅当 latest 严格更新时才打扰
+  // 4. 根据本地版本通道生成推荐;无推荐时不打扰
   const current = flowerVersion();
-  if (compareVersions(latest, current) !== 1) return;
+  const recommendation = getUpdateRecommendation(current, tags);
+  if (!recommendation) return;
 
   // 5. 打印发现新版本通知(粉色品牌色,与 banner 一致)
   console.log(
     "\n🌸 " +
-      chalk.hex("#ff6fb5")(`发现 flower-trellis 新版本 ${chalk.bold(latest)}`) +
-      chalk.gray(`(当前 ${current})`),
+      chalk.hex("#ff6fb5")(`发现 flower-trellis 新版本 ${chalk.bold(recommendation.version)}`) +
+      chalk.gray(`(当前 ${current}, 通道 ${recommendation.tag})`),
   );
 
   // 6. 非交互(-y/--yes 或非 TTY):仅打印升级命令,不弹确认、不阻塞
@@ -131,38 +237,34 @@ export async function checkForUpdate(ctx, commandLabel) {
     ctx.passthrough.includes("--yes") ||
     !process.stdin.isTTY;
   if (nonInteractive) {
-    console.log(`  · 升级:npm i -g ${PKG}@latest`);
-    console.log("  · 升级后请重跑 ft update,让新版强化包重新叠加到现有项目");
+    console.log(`  · 升级:${recommendation.command}`);
+    console.log(`  · 升级后请重跑 ft ${commandLabel},让新版强化包重新叠加到现有项目`);
     return;
   }
 
-  // 7. 交互:询问是否升级
-  const { doUpgrade } = await inquirer.prompt([
-    {
-      type: "confirm",
-      name: "doUpgrade",
-      message: `是否现在升级到 ${latest}?(升级后需重新运行命令)`,
-      default: true,
-    },
-  ]);
+  // 7. 交互:询问是否升级(@inquirer/confirm,返回 boolean)
+  const doUpgrade = await confirm({
+    message: `是否现在升级到 ${recommendation.version}(${recommendation.tag})?(升级后需重新运行命令)`,
+    default: true,
+  });
   if (!doUpgrade) {
     console.log("  · 已跳过升级");
     return;
   }
 
   // 8. 执行全局升级。失败(含 EACCES 权限问题、npm 不存在)不自行提权,降级为打印手动命令
-  const res = spawnSync("npm", ["i", "-g", `${PKG}@latest`], {
+  const res = spawnSync("npm", ["i", "-g", `${PKG}@${recommendation.tag}`], {
     stdio: "inherit",
     shell: process.platform === "win32", // Windows 上 npm 实为 npm.cmd
   });
   if (res.status === 0) {
-    console.log(`\n  ✓ 已升级到 ${latest}`);
+    console.log(`\n  ✓ 已升级到 ${recommendation.version}(${recommendation.tag})`);
     console.log(`  · 请重新运行 ft ${commandLabel} 以使用新版本`);
     console.log("  · 强化包随版本更新,升级后可 ft update 重新叠加到现有项目");
     // 当前进程内存里仍是旧代码,必须退出由用户重跑新版本(不做 re-exec,规避权限/平台/进程态坑)
     process.exit(0);
   } else {
-    console.log(`  · 自动升级失败,请手动运行:npm i -g ${PKG}@latest`);
+    console.log(`  · 自动升级失败,请手动运行:${recommendation.command}`);
     // 升级未成功:以当前版本继续 init/update,不阻断
   }
 }