flower-trellis 0.4.9 → 0.4.11

package/README.md

@@ -131,22 +131,33 @@ flower-trellis self-check --json --target .
 - **本地一致性检查**:每次启动都会比对当前安装的 `flower-trellis` / 捆绑 Trellis 版本与项目 `.trellis/.flower-manifest.json` / `.trellis/.version`;不受 `intervalHours` 限制。
 - **远程版本探测**:访问 npm registry 读取 `flower-trellis` dist-tags;受 `intervalHours` 节流,带超时,失败静默。
 
-策略和缓存统一保存在 `.trellis/.flower-manifest.json` 的 `updateCheck`:
+策略保存在 `.trellis/.flower-manifest.json` 的 `updateCheck`;运行缓存保存在 gitignored 的 `.trellis/.flower-update-check.tmp`,避免 `lastCheckedAt` 等字段反复污染 git。
+
+manifest 中只保留用户策略:
 
 ```json
 {
   "updateCheck": {
     "enabled": true,
     "policy": "ask",
-    "intervalHours": 8,
+    "intervalHours": 8
+  }
+}
+```
+
+tmp 中保存本地运行缓存:
+
+```json
+{
     "lastCheckedAt": "2026-07-07T00:00:00.000Z",
     "lastRemote": { "latest": "0.4.2", "beta": null },
     "lastStatus": "update_available",
     "lastErrorCode": null
-  }
 }
 ```
 
+旧项目如果已经在 manifest 的 `updateCheck` 里带有缓存字段,新版本会先读取兼容,并在下一次写入时清理这些旧字段。
+
 `policy` 可选:
 
 | policy | 行为 |

package/enhancements/MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "syncedAt": "2026-07-08T02:50:48.728Z",
+  "syncedAt": "2026-07-09T03:31:09.573Z",
   "syncedFrom": "vendor/skill-garden",
   "sourceCommit": "6ecfb1b46320d82aeb3e83442235f271d92aa398",
   "common": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.4.9",
+    "version": "0.4.11",
     "source": "CHANGELOG.md",
-    "body": "### 🐛 修复 Bug Fixes\n\n* **flower:** 强化项目知识发现门禁 ([d21b17e](https://github.com/SilentFlower/flower-trellis/commit/d21b17e860d3b91bb5c69c3921620d60b49608d5))\n* **flower:** 恢复 in_progress 完成门禁 ([304f5fa](https://github.com/SilentFlower/flower-trellis/commit/304f5fadfab139638cfa9658f168448a1f26f9e6))",
+    "body": "### ✨ 新功能 Features\n\n* **update-check:** 迁移运行缓存到 tmp ([986659a](https://github.com/SilentFlower/flower-trellis/commit/986659a7d3678384be055dcae0067c2c31c836fb))",
     "truncated": false
   }
 }

package/src/commands/update-check.js

@@ -4,6 +4,7 @@ import {
   manifestPath,
   readManifest,
   readUpdateCheck,
+  updateCheckCachePath,
   writeUpdateCheck,
 } from "../lib/manifest.js";
 
@@ -24,7 +25,7 @@ function assertTrellisProject(target) {
 }
 
 /**
- * flower-trellis update-check:管理 manifest 内的启动更新检查策略。
+ * flower-trellis update-check:管理启动更新检查策略,并展示本地运行缓存。
  *
  * @param {object} ctx 见 cli.js 的 parse()
  */
@@ -35,9 +36,14 @@ export async function updateCheck(ctx) {
 
   if (action === "get") {
     const manifest = readManifest(ctx.target);
+    const cachePath = updateCheckCachePath(ctx.target);
     console.log(`manifest: ${manifestPath(ctx.target)}`);
+    console.log(`cache: ${cachePath}`);
     console.log(JSON.stringify(readUpdateCheck(ctx.target), null, 2));
     if (!manifest) console.log("  · manifest 不存在,当前显示默认策略");
+    if (!fs.existsSync(cachePath)) {
+      console.log("  · cache 不存在,当前显示默认或旧 manifest 兼容缓存");
+    }
     return;
   }
 

package/src/lib/manifest.js

@@ -11,17 +11,56 @@ import path from "node:path";
  * 放在 .trellis/ 下,随项目的 Trellis 生命周期存在(uninstall 删 .trellis 时一并消失)。
  */
 const MANIFEST_REL = path.join(".trellis", ".flower-manifest.json");
+const UPDATE_CHECK_CACHE_REL = path.join(".trellis", ".flower-update-check.tmp");
 const UPDATE_POLICIES = new Set(["off", "notify", "ask", "auto"]);
-const DEFAULT_UPDATE_CHECK = {
+const UPDATE_CHECK_POLICY_KEYS = new Set(["enabled", "policy", "intervalHours"]);
+const UPDATE_CHECK_CACHE_KEYS = new Set([
+  "lastCheckedAt",
+  "lastRemote",
+  "lastReleaseNotes",
+  "lastStatus",
+  "lastErrorCode",
+]);
+const DEFAULT_UPDATE_CHECK_POLICY = {
   enabled: true,
   policy: "ask",
   intervalHours: 8,
+};
+const DEFAULT_UPDATE_CHECK_CACHE = {
   lastCheckedAt: null,
   lastRemote: null,
   lastReleaseNotes: null,
   lastStatus: null,
   lastErrorCode: null,
 };
+const DEFAULT_UPDATE_CHECK = {
+  ...DEFAULT_UPDATE_CHECK_POLICY,
+  ...DEFAULT_UPDATE_CHECK_CACHE,
+};
+
+/** 判断值是否为普通对象。 */
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+/** 判断对象是否显式包含给定字段。 */
+function hasAnyOwn(value, keys) {
+  if (!isPlainObject(value)) return false;
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) return true;
+  }
+  return false;
+}
+
+/** 从对象里取出指定字段。 */
+function pickOwn(value, keys) {
+  const raw = isPlainObject(value) ? value : {};
+  const picked = {};
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(raw, key)) picked[key] = raw[key];
+  }
+  return picked;
+}
 
 /**
  * 归一化 release notes 范围字段。
@@ -73,12 +112,126 @@ function normalizeLastReleaseNotes(value) {
   };
 }
 
-/** manifest 文件的绝对路径。 */
+/**
+ * 归一化远端 dist-tags 缓存。
+ *
+ * @param {object|null|undefined} value 原始 lastRemote 字段
+ * @returns {{latest:string|null,beta:string|null}|null} 归一化后的 dist-tags
+ */
+function normalizeLastRemote(value) {
+  return value && typeof value === "object"
+    ? {
+        latest: typeof value.latest === "string" ? value.latest : null,
+        beta: typeof value.beta === "string" ? value.beta : null,
+      }
+    : null;
+}
+
+/**
+ * 归一化启动更新检查策略字段。
+ *
+ * @param {object|null|undefined} value 原始 updateCheck 字段
+ * @returns {{enabled:boolean,policy:string,intervalHours:number}} 归一化后的策略
+ */
+function normalizeUpdateCheckPolicy(value) {
+  const raw = value && typeof value === "object" ? value : {};
+  const policy = UPDATE_POLICIES.has(raw.policy) ? raw.policy : DEFAULT_UPDATE_CHECK.policy;
+  const interval = Number(raw.intervalHours);
+  const intervalHours = Number.isFinite(interval) && interval >= 0
+    ? interval
+    : DEFAULT_UPDATE_CHECK.intervalHours;
+  return {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_UPDATE_CHECK.enabled,
+    policy,
+    intervalHours,
+  };
+}
+
+/**
+ * 归一化启动更新检查运行缓存字段。
+ *
+ * @param {object|null|undefined} value 原始缓存字段
+ * @returns {{lastCheckedAt:string|null,lastRemote:object|null,lastReleaseNotes:object|null,lastStatus:string|null,lastErrorCode:string|null}} 归一化后的缓存
+ */
+function normalizeUpdateCheckCache(value) {
+  const raw = value && typeof value === "object" ? value : {};
+  return {
+    lastCheckedAt: typeof raw.lastCheckedAt === "string" ? raw.lastCheckedAt : null,
+    lastRemote: normalizeLastRemote(raw.lastRemote),
+    lastReleaseNotes: normalizeLastReleaseNotes(raw.lastReleaseNotes),
+    lastStatus: typeof raw.lastStatus === "string" ? raw.lastStatus : null,
+    lastErrorCode: typeof raw.lastErrorCode === "string" ? raw.lastErrorCode : null,
+  };
+}
+
+/** 读取 tmp 内的 updateCheck 运行缓存;不存在或损坏时返回 null。 */
+function readUpdateCheckCacheFile(target) {
+  try {
+    return normalizeUpdateCheckCache(
+      JSON.parse(fs.readFileSync(updateCheckCachePath(target), "utf8")),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** 判断 updateCheck 是否仍含旧版 manifest 缓存字段。 */
+function hasLegacyUpdateCheckCache(updateCheck) {
+  return hasAnyOwn(updateCheck, UPDATE_CHECK_CACHE_KEYS);
+}
+
+/**
+ * 把旧 manifest 内的缓存字段迁移到 tmp。
+ *
+ * 只在 tmp 尚不存在时迁移,避免旧 manifest 里的陈旧缓存覆盖新版本地缓存。
+ */
+function migrateLegacyUpdateCheckCache(target, updateCheck) {
+  if (!hasLegacyUpdateCheckCache(updateCheck)) return;
+  if (fs.existsSync(updateCheckCachePath(target))) return;
+  fs.writeFileSync(
+    updateCheckCachePath(target),
+    JSON.stringify(normalizeUpdateCheckCache(updateCheck), null, 2) + "\n",
+  );
+}
+
+/** 写入 tmp 内的 updateCheck 运行缓存。 */
+function writeUpdateCheckCache(target, patch, legacyUpdateCheck) {
+  const current = readUpdateCheckCacheFile(target) ||
+    normalizeUpdateCheckCache(legacyUpdateCheck);
+  const cache = normalizeUpdateCheckCache({
+    ...current,
+    ...patch,
+  });
+  fs.writeFileSync(updateCheckCachePath(target), JSON.stringify(cache, null, 2) + "\n");
+  return cache;
+}
+
+/**
+ * manifest 文件的绝对路径。
+ *
+ * @param {string} target 目标项目根
+ * @returns {string} manifest 文件绝对路径
+ */
 export function manifestPath(target) {
   return path.join(target, MANIFEST_REL);
 }
 
-/** 读取 manifest;不存在或损坏时返回 null。 */
+/**
+ * updateCheck 运行缓存 tmp 文件的绝对路径。
+ *
+ * @param {string} target 目标项目根
+ * @returns {string} updateCheck 运行缓存文件绝对路径
+ */
+export function updateCheckCachePath(target) {
+  return path.join(target, UPDATE_CHECK_CACHE_REL);
+}
+
+/**
+ * 读取 manifest;不存在或损坏时返回 null。
+ *
+ * @param {string} target 目标项目根
+ * @returns {object|null} manifest 内容
+ */
 export function readManifest(target) {
   try {
     return JSON.parse(fs.readFileSync(manifestPath(target), "utf8"));
@@ -96,55 +249,65 @@ export function readManifest(target) {
  * @returns {{enabled:boolean,policy:string,intervalHours:number,lastCheckedAt:string|null,lastRemote:object|null,lastReleaseNotes:object|null,lastStatus:string|null,lastErrorCode:string|null}} 归一化后的 updateCheck
  */
 export function normalizeUpdateCheck(value) {
-  const raw = value && typeof value === "object" ? value : {};
-  const policy = UPDATE_POLICIES.has(raw.policy) ? raw.policy : DEFAULT_UPDATE_CHECK.policy;
-  const interval = Number(raw.intervalHours);
-  const intervalHours = Number.isFinite(interval) && interval >= 0
-    ? interval
-    : DEFAULT_UPDATE_CHECK.intervalHours;
-  const lastRemote = raw.lastRemote && typeof raw.lastRemote === "object"
-    ? {
-        latest: typeof raw.lastRemote.latest === "string" ? raw.lastRemote.latest : null,
-        beta: typeof raw.lastRemote.beta === "string" ? raw.lastRemote.beta : null,
-      }
-    : null;
-
   return {
-    enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_UPDATE_CHECK.enabled,
-    policy,
-    intervalHours,
-    lastCheckedAt: typeof raw.lastCheckedAt === "string" ? raw.lastCheckedAt : null,
-    lastRemote,
-    lastReleaseNotes: normalizeLastReleaseNotes(raw.lastReleaseNotes),
-    lastStatus: typeof raw.lastStatus === "string" ? raw.lastStatus : null,
-    lastErrorCode: typeof raw.lastErrorCode === "string" ? raw.lastErrorCode : null,
+    ...normalizeUpdateCheckPolicy(value),
+    ...normalizeUpdateCheckCache(value),
   };
 }
 
 /**
- * 读取 manifest 里的启动更新检查配置。
+ * 读取启动更新检查配置。
+ *
+ * 返回 manifest 策略与 tmp 运行缓存的合并视图;tmp 不存在时兼容读取旧 manifest 缓存字段。
  *
  * @param {string} target 目标项目根
  * @returns {ReturnType<typeof normalizeUpdateCheck>} 归一化后的配置
  */
 export function readUpdateCheck(target) {
-  return normalizeUpdateCheck(readManifest(target)?.updateCheck);
+  const manifestUpdateCheck = readManifest(target)?.updateCheck;
+  return {
+    ...normalizeUpdateCheckPolicy(manifestUpdateCheck),
+    ...(
+      readUpdateCheckCacheFile(target) ||
+      // 兼容旧版本:首次写入前仍可复用 manifest 里的运行缓存。
+      normalizeUpdateCheckCache(manifestUpdateCheck)
+    ),
+  };
 }
 
 /**
- * 写入启动更新检查配置,保留 manifest 其它安装清单字段。
+ * 写入启动更新检查配置。
+ *
+ * 策略字段写入 `.flower-manifest.json`;运行缓存字段写入 `.flower-update-check.tmp`。
+ * 若旧 manifest 仍包含缓存字段,本函数会在写入时顺带清理,避免运行态继续进入 git。
  *
  * @param {string} target 目标项目根
  * @param {object} patch 要合并进 updateCheck 的字段
- * @returns {object} 写入后的 manifest
+ * @returns {object|null} 写入后的 manifest;没有 manifest 且仅写缓存时返回 null
  */
 export function writeUpdateCheck(target, patch) {
-  const current = readManifest(target) || {};
-  const updateCheck = normalizeUpdateCheck({
-    ...normalizeUpdateCheck(current.updateCheck),
-    ...(patch || {}),
-  });
-  const next = { ...current, updateCheck };
+  const current = readManifest(target);
+  const policyPatch = pickOwn(patch, UPDATE_CHECK_POLICY_KEYS);
+  const cachePatch = pickOwn(patch, UPDATE_CHECK_CACHE_KEYS);
+  const hasPolicyPatch = Object.keys(policyPatch).length > 0;
+  const hasCachePatch = Object.keys(cachePatch).length > 0;
+  const hasLegacyCache = hasLegacyUpdateCheckCache(current?.updateCheck);
+
+  if (hasCachePatch && current) {
+    writeUpdateCheckCache(target, cachePatch, current.updateCheck);
+  } else if (hasLegacyCache) {
+    migrateLegacyUpdateCheckCache(target, current.updateCheck);
+  }
+
+  if (!hasPolicyPatch && !hasLegacyCache) return current;
+
+  const next = {
+    ...(current || {}),
+    updateCheck: normalizeUpdateCheckPolicy({
+      ...normalizeUpdateCheckPolicy(current?.updateCheck),
+      ...policyPatch,
+    }),
+  };
   fs.writeFileSync(manifestPath(target), JSON.stringify(next, null, 2) + "\n");
   return next;
 }
@@ -152,7 +315,8 @@ export function writeUpdateCheck(target, patch) {
 /**
  * 写入 manifest。
  *
- * 若调用方没有显式传入 `updateCheck`,保留目标项目已有策略与缓存,避免全装重写时覆盖用户选择。
+ * 若调用方没有显式传入 `updateCheck`,保留目标项目已有策略,避免全装重写时覆盖用户选择。
+ * 运行缓存会迁移到 `.flower-update-check.tmp`,不得继续写入 manifest。
  *
  * @param {string} target 目标项目根
  * @param {object} data manifest 新内容
@@ -160,10 +324,14 @@ export function writeUpdateCheck(target, patch) {
 export function writeManifest(target, data) {
   const current = readManifest(target);
   const next = { ...data };
+  if (hasLegacyUpdateCheckCache(current?.updateCheck)) {
+    migrateLegacyUpdateCheckCache(target, current.updateCheck);
+  }
   if (Object.prototype.hasOwnProperty.call(data, "updateCheck")) {
-    next.updateCheck = normalizeUpdateCheck(data.updateCheck);
+    migrateLegacyUpdateCheckCache(target, data.updateCheck);
+    next.updateCheck = normalizeUpdateCheckPolicy(data.updateCheck);
   } else {
-    next.updateCheck = normalizeUpdateCheck(current?.updateCheck);
+    next.updateCheck = normalizeUpdateCheckPolicy(current?.updateCheck);
   }
   fs.writeFileSync(manifestPath(target), JSON.stringify(next, null, 2) + "\n");
 }

package/src/lib/self-check.js

@@ -119,6 +119,46 @@ function releaseNotesFromMetadata(metadata, range) {
   return buildReleaseNotesSummary(metadata?.releaseNotesByVersion, range);
 }
 
+/**
+ * 安全执行 npm metadata 拉取。
+ *
+ * 默认 fetcher 已经吞掉网络错误;这里再兜底测试注入的 fetcher,确保 release notes
+ * 补拉失败不会破坏 self-check 主流程。
+ *
+ * @param {() => Promise<object|null>} fetchMetadata npm metadata 拉取函数
+ * @returns {Promise<object|null>} registry metadata,失败时为 null
+ */
+async function safeFetchPackageUpdateMetadata(fetchMetadata) {
+  try {
+    return await fetchMetadata();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 缓存命中但缺少摘要时,主动补拉 release notes。
+ *
+ * 这个补拉只服务当前 actionable 提示的摘要展示,不能把失败写成新的远程版本证据;
+ * 成功时也只写回 lastReleaseNotes,保持 lastRemote 仍只记录 dist-tags。
+ *
+ * @param {string} target 目标项目根
+ * @param {object|null} manifest 目标项目 manifest
+ * @param {boolean} writeCache 是否允许写缓存
+ * @param {object|null} range release notes 范围
+ * @param {() => Promise<object|null>} fetchMetadata npm metadata 拉取函数
+ * @returns {Promise<object|null>} release notes 摘要;范围有效但不可用时返回 unavailable 摘要
+ */
+async function fetchMissingReleaseNotes(target, manifest, writeCache, range, fetchMetadata) {
+  if (!range) return null;
+  const metadata = await safeFetchPackageUpdateMetadata(fetchMetadata);
+  const releaseNotes = releaseNotesFromMetadata(metadata, range);
+  if (releaseNotes && !releaseNotes.unavailable && writeCache && manifest) {
+    writeUpdateCheck(target, { lastReleaseNotes: releaseNotes });
+  }
+  return releaseNotes;
+}
+
 /** 检查目标目录 git 工作区是否 clean。 */
 function gitSafety(target) {
   const common = {
@@ -312,12 +352,15 @@ export function safetyState(target, status, command) {
  * 构建启动自更新检查结果。
  *
  * @param {string} target 目标项目根
- * @param {{writeCache?: boolean, forceRemote?: boolean}} options 检查选项
+ * @param {{writeCache?: boolean, forceRemote?: boolean, fetchMetadata?: () => Promise<object|null>}} options 检查选项
  * @returns {Promise<object>} 结构化检查结果
  */
 export async function buildSelfCheck(target, options = {}) {
   const writeCache = options.writeCache !== false;
   const forceRemote = options.forceRemote === true;
+  const fetchMetadata = typeof options.fetchMetadata === "function"
+    ? options.fetchMetadata
+    : fetchPackageUpdateMetadata;
   const now = new Date();
   const absoluteTarget = path.resolve(target);
   const trellisDir = path.join(absoluteTarget, ".trellis");
@@ -404,11 +447,19 @@ export async function buildSelfCheck(target, options = {}) {
     }
     if (projectOutOfSync) {
       const releaseNotesRange = projectReleaseNotesRange(projectFlower, currentFlower);
+      const releaseNotes = cachedReleaseNotes(updateCheck, releaseNotesRange) ||
+        await fetchMissingReleaseNotes(
+          absoluteTarget,
+          manifest,
+          writeCache,
+          releaseNotesRange,
+          fetchMetadata,
+        );
       return projectOutOfSyncResult(base, absoluteTarget, {
         tags,
         fromCache: true,
         skipped: true,
-      }, cachedReleaseNotes(updateCheck, releaseNotesRange));
+      }, releaseNotes);
     }
     return {
       ...base,
@@ -418,7 +469,7 @@ export async function buildSelfCheck(target, options = {}) {
     };
   }
 
-  const metadata = await fetchPackageUpdateMetadata();
+  const metadata = await safeFetchPackageUpdateMetadata(fetchMetadata);
   if (!metadata) {
     if (writeCache && manifest) {
       writeUpdateCheck(absoluteTarget, {

package/src/lib/update-check.js

@@ -348,7 +348,7 @@ export function getUpdateRecommendation(current, tags) {
   return null;
 }
 
-/** 尽力而为刷新目标项目 manifest 里的远端探测缓存。 */
+/** 尽力而为刷新目标项目的远端探测缓存。 */
 function rememberRemoteTags(target, tags, status, releaseNotes = null) {
   try {
     if (!readManifest(target)) return;