@inventec/dsh-copilot-auth 1.2.3 → 1.2.4

package/README.md

@@ -81,6 +81,7 @@ pi-ai 的模型目录是打包时硬编码的 JSON：上游新增模型（如 ge
 - **数据源与回退**：账号可用模型现场拉取（失败回退凭证缓存）；目录数据从 npm 拉取最新 pi-ai tarball（强制 `dist.integrity` 校验、超时与大小上限、tar 严格解析），失败时可改用内置覆盖层（0.85.1 收割，integrity `sha512-+VgVIJDkDO2efYJKEEqvPTH4zmnIaXdAppGbO+vKFA9qy5PdhFiAenuFAkU+oiCSfOC4dMHDyrjdQeL4ZoC5CQ==`）出 diff。
 - **只增不更新**：合并只补充本机从未见过的模型条目；上游对已有 id 的元数据修正（api 归属、contextWindow 等）不会同步——这是「永不覆盖」语义的代价（ADR 0001）。
 - **digest 绑定**：preview 与 apply 之间以输入 digest（settings 完整配置 / 可用模型 / 本地目录 / 目录来源）绑定，任何漂移即 409 并要求重新预览确认。
+- **可写性门禁（v1.2.4 起，ADR 0002）**：dsh-desktop（Electron）把整个运行时树打包进只读的 `resources/app.asar`，pi-ai 是其中唯一副本——读一切正常、写必被拒。插件在写盘前对目标做可写性分类（asar 路径识别 + 探针文件实测）：不可写时 preview/`/status` 暴露 `catalogWritable:false`、UI 置灰刷新入口并给出解释文案，apply 在 write-ahead **之前**以 400 `catalog-not-writable` 结构化快速失败（绝不留下 prepared journal）；boot 序列遇到只读目标同样不重试写盘，journal/overlay 原样保留，目标变可写（如桌面版改为解包 pi-ai）后恢复/自愈自动完成。Web/服务部署形态（pi-ai 在真实磁盘）行为不变。
 
 ## 工作原理
 
@@ -95,7 +96,7 @@ pi-ai 的模型目录是打包时硬编码的 JSON：上游新增模型（如 ge
 
 ```bash
 npm install
-npm test        # node:test：patch 结构 + host/目录/状态机/启动序列共 107 条
+npm test        # node:test：patch 结构 + host/目录/状态机/启动序列/可写性门禁共 114 条（CI 跑 ubuntu/windows/macos 三平台矩阵）
 npm run build   # esbuild 打包 client 到 lib/client.js（__ModuleLoader__ 信封）
 npm pack --dry-run
 ```
@@ -125,6 +126,7 @@ npm pack --dry-run
 - 模型目录只在「尚不存在」时由登录成功兜底填充一次，填充后归用户所有：账号新增的模型不会自动出现——用 GHC 设置页的「**刷新可用模型目录**」同步（见上节），或在 Models 页手动添加
 - 模型目录只写入 pi-ai 内置目录已描述的模型：目录快照外的新模型需先经「刷新可用模型目录」补入目录条目（数据级补丁，pi-ai 版本不变）才会出现在可选列表
 - DSH 升级后自愈仅在 pi-ai 基线版本不变（0.84.4）时重放；跨版本且条目未原生存在时上报 `self-heal-incompatible`，不修改安装树（重新执行一次手动刷新即可在新基线上激活）
+- **dsh-desktop（Electron 桌面版）无法刷新模型目录**：运行时树（含 pi-ai 唯一副本）打包在只读的 `app.asar` 内，数据级目录补丁物理不可写。v1.2.4 起该形态被显式识别：刷新入口置灰 + `catalog-not-writable` 结构化报错（v1.2.3 及之前会抛 `ENOENT ... not found in ...app.asar` 天书并遗留 prepared journal）。登录/注销/settings 模型目录镜像不受影响；目录刷新请用 Web/服务部署形态（ADR 0002）
 - 并发保护为宿主单进程内 mutex，**不支持多实例/多进程并发刷新**
 - 状态落盘后的目录 fsync 仅在 POSIX 执行：Windows 无目录 fsync 语义（对目录句柄 fsync 必然 `EPERM`），win32 直接跳过、不再刷告警，目录项一致性由 NTFS 元数据日志保证（v1.2.3 起，issue #1）；POSIX 行为不变
 

package/lib/client.js

@@ -44,7 +44,7 @@ var routes = () => ({
 });
 
 // src/refresh-flow.mjs
-var initial = Object.freeze({ name: "idle" });
+var initial = Object.freeze({ name: "idle", catalogWritable: null });
 function reduce(state, event) {
   switch (state.name) {
     case "idle":
@@ -59,8 +59,11 @@ function reduce(state, event) {
         const refresh = event.status?.refresh;
         if (!event.status) return [state, null];
         if (refresh?.lastError === "state-corrupt") return [{ name: "failed", error: "state-corrupt" }, null];
-        if (refresh?.pendingRestart === true) return [{ name: "restartNeeded" }, null];
-        return state.name === "idle" ? [state, null] : [state, null];
+        if (refresh?.pendingRestart === true) {
+          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null }, null];
+        }
+        const writable = refresh && "catalogWritable" in refresh ? refresh.catalogWritable : state.catalogWritable ?? null;
+        return [{ ...state, catalogWritable: writable }, null];
       }
       return [state, null];
     }
@@ -192,7 +195,8 @@ var DICTS = {
     srcLatest: "Catalog source: latest pi-ai from npm",
     srcLocal: "Catalog source: local only (npm fetch failed)",
     srcOverlay: "Catalog source: bundled overlay (offline bootstrap)",
-    none: "(none)"
+    none: "(none)",
+    notWritable: "This DSH installation packages the model catalog read-only (inside app.asar) \u2014 the refresh cannot be written. Use a web/service deployment for catalog refresh, or wait for a desktop build that unpacks pi-ai."
   },
   zh: {
     nav: "GHC\u8BBE\u7F6E",
@@ -235,7 +239,8 @@ var DICTS = {
     srcLatest: "\u76EE\u5F55\u6765\u6E90\uFF1Anpm \u6700\u65B0 pi-ai",
     srcLocal: "\u76EE\u5F55\u6765\u6E90\uFF1A\u4EC5\u672C\u5730\u76EE\u5F55\uFF08npm \u62C9\u53D6\u5931\u8D25\uFF09",
     srcOverlay: "\u76EE\u5F55\u6765\u6E90\uFF1A\u5185\u7F6E\u8986\u76D6\u5C42\uFF08\u79BB\u7EBF bootstrap\uFF09",
-    none: "\uFF08\u65E0\uFF09"
+    none: "\uFF08\u65E0\uFF09",
+    notWritable: "\u5F53\u524D DSH \u5B89\u88C5\u628A\u6A21\u578B\u76EE\u5F55\u6253\u5305\u5728\u53EA\u8BFB\u7684 app.asar \u5185\uFF0C\u5237\u65B0\u65E0\u6CD5\u5199\u5165\u3002\u8BF7\u5728 Web/\u670D\u52A1\u90E8\u7F72\u5F62\u6001\u4E0B\u5237\u65B0\u76EE\u5F55\uFF0C\u6216\u7B49\u5F85\u684C\u9762\u7248\u63D0\u4F9B\u53EF\u5199\u5E03\u5C40\u540E\u91CD\u8BD5\u3002"
   }
 };
 var NAV_TEXTS = Object.keys(DICTS).map((locale) => DICTS[locale].nav);
@@ -424,10 +429,23 @@ function RefreshModal({ t, flow, onConfirm, onCancel, onOverlay }) {
       "\u26A0 ",
       t("riskRestart")
     ] }),
+    p.catalogWritable === false && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.error, children: [
+      "\u26A0 ",
+      t("notWritable")
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.modalActions, children: [
       p.catalogSource === "local" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: { ...styles.button, ...styles.secondary, marginRight: "auto" }, onClick: onOverlay, children: t("overlayBtn") }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: { ...styles.button, ...styles.secondary }, onClick: onCancel, children: t("cancel") }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: { ...styles.button, ...styles.primary }, onClick: onConfirm, children: t("confirmRefresh") })
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        "button",
+        {
+          type: "button",
+          style: { ...styles.button, ...styles.primary, ...p.catalogWritable === false ? { opacity: 0.5, cursor: "not-allowed" } : null },
+          disabled: p.catalogWritable === false,
+          onClick: onConfirm,
+          children: t("confirmRefresh")
+        }
+      )
     ] })
   ] }) });
 }
@@ -551,18 +569,22 @@ function CopilotSection({ t = (key) => DICTS.en[key] ?? key }) {
         "button",
         {
           type: "button",
-          style: { ...styles.button, ...styles.primary },
-          disabled: flow.name === "previewing" || flow.name === "applying",
+          style: { ...styles.button, ...styles.primary, ...flow.catalogWritable === false ? { opacity: 0.5, cursor: "not-allowed" } : null },
+          disabled: flow.catalogWritable === false || flow.name === "previewing" || flow.name === "applying",
           onClick: () => drive({ type: "start" }),
           children: flow.name === "previewing" ? t("refreshing") : flow.name === "applying" ? t("applying") : t("refreshNow")
         }
       )
     ] }),
+    page === "authorized" && flow.catalogWritable === false && flow.name !== "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
+      "\u26A0 ",
+      t("notWritable")
+    ] }),
     page === "authorized" && flow.name === "restartNeeded" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
       "\u26A0 ",
       t("restartNeeded")
     ] }),
-    page === "authorized" && flow.name === "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.error, children: flow.error === "state-corrupt" ? t("stateCorrupt") : flow.error }),
+    page === "authorized" && flow.name === "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.error, children: flow.error === "state-corrupt" ? t("stateCorrupt") : flow.error === "catalog-not-writable" ? t("notWritable") : flow.error }),
     flow.name === "confirming" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       RefreshModal,
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventec/dsh-copilot-auth",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "为内置 Copilot 提供方补设备码登录/注销设置页，预置开箱路由；凭据入内置凭据库，模型目录兜底不覆盖定制。适配 DSH 0.1.7+（settings API 重塑后；≤0.1.5 请用 1.1.x）。",
   "type": "module",
   "license": "MIT",

package/src/catalog.mjs

@@ -1,7 +1,7 @@
 // catalog.mjs — 数据核心：tgz 严格解析、条目校验、只增不更新合并、diff、digest、
 // pi-ai 安装定位。合并语义「只增不更新」（ADR 0001）：已有 id 的元数据永不覆盖。
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { gunzipSync } from "node:zlib";
 
@@ -154,3 +154,45 @@ export function findPiAiInstallation({ startPath } = {}) {
   } catch { /* 安装树结构变化 → null（调用方降级） */ }
   return null;
 }
+
+// ==================== 安装目标可写性分类（desktop asar 只读问题，ADR 0002） ====================
+// dsh-desktop（Electron）把整个运行时树打进 resources/app.asar，pi-ai 是其中唯一副本：
+// asar 虚拟文件系统读没问题、创建/写入必被拒（ENOENT "... not found in <archive>"）。
+// 数据级目录补丁在写盘前必须先分类目标，把"物理不可写"变成结构化错误而不是天书 ENOENT。
+
+// Electron 的 asar 拦截按"路径中任一段以 .asar 结尾"判定（大小写不敏感，分隔符 / 与 \ 都认，
+// Win 路径在 POSIX 主机上测试时也要能识别）。.asar.unpacked 不以 .asar 结尾，不会误判。
+export function isAsarPath(p) {
+  const s = String(p ?? "");
+  if (/\.asar$/i.test(s)) return true;
+  return s.split(/[\\/]/).some((seg) => /\.asar$/i.test(seg));
+}
+
+// 功能性可写探测：在目录内排他创建 + 删除一个探针文件。覆盖 asar 之外的不可写形态
+// （只读卷、根属主安装、ACL 拒绝——win32 chmod 弱语义下唯一可靠的通用手段）。
+// 探针文件名带 UUID，排他创建，任何失败路径都尝试清理并返回 false。
+export function probeWritable(dir) {
+  const probe = join(dir, `.copilot-auth-write-probe-${randomUUID()}`);
+  let fd;
+  try {
+    fd = openSync(probe, "wx");
+    closeSync(fd);
+    fd = undefined;
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* 已关闭 */ }
+    }
+    try { unlinkSync(probe); } catch { /* 探针可能未创建成功 */ }
+  }
+}
+
+// 分类结果平铺进安装对象：writable: boolean；不可写时 unwritableReason: "asar" | "probe-failed"。
+// writableProbe 仅作测试注入钩子（生产恒用默认实现）。
+export function classifyCatalogTarget(catalogFile, writableProbe = probeWritable) {
+  if (isAsarPath(catalogFile)) return { writable: false, unwritableReason: "asar" };
+  if (!writableProbe(dirname(catalogFile))) return { writable: false, unwritableReason: "probe-failed" };
+  return { writable: true, unwritableReason: null };
+}

package/src/host.mjs

@@ -1,14 +1,14 @@
 // host 半区：cordis 插件。注册 6 条 exact 路由，把内置 github-copilot 的
 // OAuth 设备码流（ctx.authorization）暴露给 Web client，并提供「手动刷新可用
 // 模型目录」（数据级目录补丁，pi-ai 代码版本不动；只读 GET /models 适配显式
-// 耦合 pi-ai 0.84.4，详见 CONTEXT.md 与 ADR 0001）。
+// 耦合 pi-ai 0.84.4，详见 GLOSSARY.md 与 ADR 0001）。
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { CREDENTIAL_KEY, emptyState, routes } from "./shared.mjs";
 import { readJson, writeJsonAtomic, createMutex } from "./atomic-json.mjs";
-import { mergeCatalog, diffModels, digest, findPiAiInstallation } from "./catalog.mjs";
+import { mergeCatalog, diffModels, digest, findPiAiInstallation, classifyCatalogTarget } from "./catalog.mjs";
 import { fetchLatestCatalog } from "./catalog-fetch.mjs";
 import { fetchLiveAvailableModelIds } from "./copilot-models.mjs";
 import { loadState, saveState, freshState, createJournal, advanceJournal, restartMarker, setLastError, clearLastError } from "./state.mjs";
@@ -163,22 +163,37 @@ function readBody(req) {
 // 版本与 catalog 同根解析（R3-8）：注入 catalogFile 时 version 取其所在根的
 // package.json（opts.piAiVersion 为测试钩子）；生产走 findPiAiInstallation()。
 function resolveInstall(opts) {
+  let install;
   if (opts.catalogFile) {
-    if (opts.piAiVersion) return { catalogFile: opts.catalogFile, version: opts.piAiVersion };
-    const root = dirname(dirname(dirname(dirname(opts.catalogFile))));
-    const packageJsonFile = join(root, "package.json");
-    const pkg = JSON.parse(readFileSync(packageJsonFile, "utf8"));
-    return { catalogFile: opts.catalogFile, packageJsonFile, version: pkg.version };
+    if (opts.piAiVersion) {
+      install = { catalogFile: opts.catalogFile, version: opts.piAiVersion };
+    } else {
+      const root = dirname(dirname(dirname(dirname(opts.catalogFile))));
+      const packageJsonFile = join(root, "package.json");
+      const pkg = JSON.parse(readFileSync(packageJsonFile, "utf8"));
+      install = { catalogFile: opts.catalogFile, packageJsonFile, version: pkg.version };
+    }
+  } else {
+    const found = findPiAiInstallation();
+    if (!found) throw new Error("pi-ai installation not found");
+    install = found;
   }
-  const found = findPiAiInstallation();
-  if (!found) throw new Error("pi-ai installation not found");
-  return found;
+  // 可写性门禁（ADR 0002）：desktop asar 打包形态下 catalogFile 在只读归档内——读一切
+  // 正常、写必被拒。这里统一分类，apply/boot 据此结构化快速失败而非抛天书 ENOENT。
+  // opts.writableProbe 为测试注入钩子（生产恒用默认探测实现）。
+  return { ...install, ...classifyCatalogTarget(install.catalogFile, opts.writableProbe) };
 }
 
 function readLocalCatalog(opts) {
-  const file = resolveInstall(opts).catalogFile;
-  const bytes = readFileSync(file);
-  return { file, bytes, catalog: JSON.parse(bytes.toString("utf8")) };
+  const install = resolveInstall(opts);
+  const bytes = readFileSync(install.catalogFile);
+  return {
+    file: install.catalogFile,
+    bytes,
+    catalog: JSON.parse(bytes.toString("utf8")),
+    writable: install.writable,
+    unwritableReason: install.unwritableReason,
+  };
 }
 
 // 账号可用模型：现场拉取（显式耦合 0.84.4）→ 任何失败回退凭证缓存 availableModelIds
@@ -299,6 +314,13 @@ async function bootRefresh(ctx, opts) {
       }
       const replay = mergeCatalog(readDiskCatalog(), state.journal.pendingOverlay);
       if (replay.added.length > 0) {
+        // 可写性门禁（ADR 0002）：不可写目标不重试写盘——journal 原样保留，安装将来
+        // 变可写（如桌面版改为解包 pi-ai）后本恢复自动完成。零写入、可 grep 的 lastError。
+        if (!install.writable) {
+          state = setLastError(state, `catalog-not-writable (${install.unwritableReason}): pi-ai catalog is read-only; prepared journal kept, refresh will complete automatically once the target becomes writable`);
+          saveState(stateFile, state);
+          return;
+        }
         writeJsonAtomic(install.catalogFile, replay.merged);
         bootPatched = true;
       }
@@ -327,11 +349,18 @@ async function bootRefresh(ctx, opts) {
         } else if (install.version === baseline) {
           const replay = mergeCatalog(readDiskCatalog(), state.appliedOverlay);
           if (replay.added.length > 0) {
-            writeJsonAtomic(install.catalogFile, replay.merged); // 原子重放
-            bootPatched = true;
-            state.restartState = restartMarker("self-heal", digest(state.appliedOverlay));
-            state = clearLastError(state);
-            saveState(stateFile, state);
+            // 可写性门禁（ADR 0002）：自愈同理不重试写盘——appliedOverlay 保留，
+            // 目标可写后下一 boot 重放；不抛错、不阻断启动序列。
+            if (!install.writable) {
+              state = setLastError(state, `catalog-not-writable (${install.unwritableReason}): pi-ai catalog is read-only; self-heal deferred, overlay entries stay pending`);
+              saveState(stateFile, state);
+            } else {
+              writeJsonAtomic(install.catalogFile, replay.merged); // 原子重放
+              bootPatched = true;
+              state.restartState = restartMarker("self-heal", digest(state.appliedOverlay));
+              state = clearLastError(state);
+              saveState(stateFile, state);
+            }
           }
         } else {
           const missing = overlayIds.filter((id) => !diskIds(readDiskCatalog()).has(id));
@@ -566,6 +595,7 @@ export function apply(ctx, opts = {}) {
         piAiVersion: install?.version ?? null,
         catalogDigest,
         catalogFile: install?.catalogFile ?? null,
+        catalogWritable: install ? install.writable === true : null,
       };
       json(res, 200, { configured, syncError: lastSyncError, refresh });
     },
@@ -615,6 +645,7 @@ export function apply(ctx, opts = {}) {
           source: inputs.source,
           catalogSource: inputs.resolved.catalogSource,
           catalogError: inputs.resolved.catalogError,
+          catalogWritable: inputs.local.writable,
           skipped: inputs.merged.skipped,
           added: inputs.diff.added,
           removed: inputs.diff.removed,
@@ -665,6 +696,14 @@ export function apply(ctx, opts = {}) {
           }
           // digest 全部一致后才解析版本（写入失败点上移，500 不留 journal）
           const install = resolveInstall(opts);
+          // 可写性门禁（ADR 0002）：不可写目标在 write-ahead 之前快速失败——绝不留
+          // prepared journal（desktop asar 形态下那会让每个 boot 都重试写归档）。
+          if (!install.writable) {
+            return {
+              code: 400,
+              payload: { ok: false, error: "catalog-not-writable", reason: install.unwritableReason, catalogFile: install.catalogFile },
+            };
+          }
           const stateFile = opts.stateFile ?? defaultStateFile();
           const patchedBytes = Buffer.from(JSON.stringify(inputs.merged.merged, null, 2) + "\n", "utf8");
           let state = loadState(stateFile);

package/src/refresh-flow.mjs

@@ -6,7 +6,7 @@
 // POST preview）→ 成功进 confirming(staleNotice)；restartNeeded 可由 /status 水合。
 import { routes } from "./shared.mjs";
 
-export const initial = Object.freeze({ name: "idle" });
+export const initial = Object.freeze({ name: "idle", catalogWritable: null });
 
 // reduce(state, event) → [nextState, effect | null]
 // effect 为数据化指令：{type:"preview",mode} | {type:"apply",mode,digests} | {type:"status"}
@@ -24,8 +24,13 @@ export function reduce(state, event) {
         const refresh = event.status?.refresh;
         if (!event.status) return [state, null]; // status 拉取失败不硬失败
         if (refresh?.lastError === "state-corrupt") return [{ name: "failed", error: "state-corrupt" }, null];
-        if (refresh?.pendingRestart === true) return [{ name: "restartNeeded" }, null];
-        return state.name === "idle" ? [state, null] : [state, null];
+        if (refresh?.pendingRestart === true) {
+          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null }, null];
+        }
+        // 干净水合：catalogWritable 随 /status 落态（desktop asar 只读形态 → false，
+        // UI 置灰刷新入口）；旧宿主不携带该字段时保持现值不回退。
+        const writable = refresh && "catalogWritable" in refresh ? refresh.catalogWritable : state.catalogWritable ?? null;
+        return [{ ...state, catalogWritable: writable }, null];
       }
       return [state, null];
     }