dsh-plugin-compat-check 0.1.0 → 0.1.2

package/lib/client.js

@@ -1,10 +1,10 @@
-// Client half of dsh-plugin-compat-check — the overview table (Plan.md §5 C2).
+// Client half of dsh-plugin-compat-check — the overview table (docs/Plan.md §5 C2).
 //
 // This file is a PREBUILT artifact: the host does not build plugin client code.
 // If it moves to src/ the entry fails to activate with "run pnpm build before
 // launch", so it stays here as plain, dependency-free JS.
 //
-// Contract (Plan.md §7.3, verified on 0.2.0-rc.2):
+// Contract (docs/Plan.md §7.3, verified on 0.2.0-rc.2):
 //   window.__ModuleLoader__.load({ id: "<package name>", factory })
 //   factory(require) -> { name, inject: ["slots"], apply(ctx) }
 //
@@ -27,12 +27,512 @@ window.__ModuleLoader__.load({
     var exports = module.exports;
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 
+    // BEGIN GENERATED REPORT CONTRACT
+    var ReportContract = (function () {
+/** Browser-safe runtime type contracts. No imports: staged into the prebuilt
+ * client and plugin host from this single source. Unknown additive fields are
+ * preserved. Version changes or missing evidence fail closed as tool errors.
+ * @typedef {{status:'complete'|'limited',verifiedCalls:number,limitations:string[]}} Coverage
+ * @typedef {{category:string,severity:'fatal'|'feature-dead'|'degraded',certainty:'certain'|'suspected',impactBasis:'measured'|'inferred',location:object|null}} Finding
+ * @typedef {{mode:'catalogue'|'runtime',bound:boolean,usable:boolean,notes:string[],profileId:string|null,dshVersion:string|null,probedAt:string|null}} Observation
+ */
+const REPORT_SCHEMA = 1;
+const REPORT_KIND = "plugin-compat-check/result";
+const ENVELOPE_KIND = "plugin-compat-check/report";
+const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const text = (v) => typeof v === "string" && v.length > 0;
+const nullableText = (v) => v === null || typeof v === "string";
+const integer = (v) => Number.isSafeInteger(v) && v >= 0;
+const strings = (v) =>
+  Array.isArray(v) && v.every((x) => typeof x === "string");
+const verdicts = ["ok", "partial", "broken", "unknown"];
+const severities = ["fatal", "feature-dead", "degraded"];
+const certainties = ["certain", "suspected"];
+const dispositions = [
+  "finding",
+  "client-side",
+  "self-provided",
+  "runtime-facility",
+  "filtered",
+  "abstained",
+  "guarded",
+  "no-calls",
+  "unknown",
+];
+function coherentVerdict(p) {
+  if (!Array.isArray(p.findings)) return false;
+  return (
+    p.verdict === "unknown" ||
+    p.verdict ===
+      (p.findings.some((f) => f?.severity === "fatal")
+        ? "broken"
+        : p.findings.length
+          ? "partial"
+          : "ok")
+  );
+}
+function snapshotFinding(f) {
+  return (
+    record(f) &&
+    text(f.key) &&
+    text(f.category) &&
+    severities.includes(f.severity) &&
+    certainties.includes(f.certainty) &&
+    nullableText(f.location)
+  );
+}
+function checkedEntry(v) {
+  return record(v) && text(v.service) && dispositions.includes(v.disposition);
+}
+// Producers resolve relative observation paths before serialization. Lexical
+// normalization here is platform independent and needs no browser Node shim.
+function pathIdentity(v) {
+  const normalized = v.replace(/\\/g, "/");
+  const parts = [];
+  for (const part of normalized.split("/")) {
+    if (part === "..") parts.pop();
+    else if (part && part !== ".") parts.push(part);
+  }
+  return (normalized.startsWith("/") ? "/" : "") + parts.join("/");
+}
+function need(errors, condition, path) {
+  if (!condition) errors.push(path);
+}
+function exitCodeForSummary(summary) {
+  return summary.broken > 0
+    ? 2
+    : summary.partial > 0 || summary.unknown > 0
+      ? 1
+      : 0;
+}
+function createFailure(error, options = {}) {
+  return {
+    ...options,
+    schemaVersion: REPORT_SCHEMA,
+    kind: REPORT_KIND,
+    ok: false,
+    exitCode: 3,
+    toolVersion: options.toolVersion ?? null,
+    error: String(error || "Unknown tool error"),
+    inputs: options.inputs || {},
+  };
+}
+function validateObservation(value) {
+  const e = [];
+  if (!record(value)) return ["observation"];
+  need(e, ["runtime", "catalogue"].includes(value.mode), "observation.mode");
+  need(e, typeof value.bound === "boolean", "observation.bound");
+  need(e, typeof value.usable === "boolean", "observation.usable");
+  need(e, strings(value.notes), "observation.notes");
+  for (const key of ["profileId", "dshVersion", "probedAt"])
+    need(e, nullableText(value[key]), "observation." + key);
+  if (value.probedAt !== null)
+    need(
+      e,
+      Number.isFinite(Date.parse(value.probedAt)),
+      "observation.probedAt",
+    );
+  need(
+    e,
+    (value.mode === "runtime") === value.usable,
+    "observation.mode/usable",
+  );
+  return e;
+}
+function validateFinding(f) {
+  const e = [];
+  if (!record(f)) return ["finding"];
+  need(e, text(f.category), "finding.category");
+  need(e, severities.includes(f.severity), "finding.severity");
+  need(e, certainties.includes(f.certainty), "finding.certainty");
+  need(
+    e,
+    ["inferred", "measured"].includes(f.impactBasis),
+    "finding.impactBasis",
+  );
+  need(e, text(f.impact), "finding.impact");
+  need(e, text(f.basis), "finding.basis");
+  for (const key of ["service", "method"])
+    if (f[key] !== undefined) need(e, nullableText(f[key]), "finding." + key);
+  need(
+    e,
+    f.location === null ||
+      (record(f.location) &&
+        text(f.location.file) &&
+        Number.isSafeInteger(f.location.line) &&
+        f.location.line > 0),
+    "finding.location",
+  );
+  if (f.evidence !== undefined) need(e, record(f.evidence), "finding.evidence");
+  if (record(f.location)) {
+    for (const key of ["column", "start", "end"])
+      if (f.location[key] !== undefined && f.location[key] !== null)
+        need(e, integer(f.location[key]), "finding.location." + key);
+    if (integer(f.location.start) && integer(f.location.end))
+      need(e, f.location.end >= f.location.start, "finding.location.span");
+  }
+  return e;
+}
+function validateBaseline(value) {
+  const e = [];
+  if (!record(value) || value.schemaVersion !== 2)
+    return ["baseline.schemaVersion"];
+  need(e, nullableText(value.dshVersion), "baseline.dshVersion");
+  need(
+    e,
+    record(value.identity) && text(value.identity.mode),
+    "baseline.identity",
+  );
+  if (!record(value.plugins)) return [...e, "baseline.plugins"];
+  for (const [name, p] of Object.entries(value.plugins)) {
+    if (!record(p)) {
+      e.push("baseline.plugin:" + name);
+      continue;
+    }
+    need(
+      e,
+      nullableText(p.version) && verdicts.includes(p.verdict),
+      "baseline.plugin:" + name,
+    );
+    need(e, Array.isArray(p.findings), "baseline.findings:" + name);
+    need(e, coherentVerdict(p), "baseline.verdict/findings:" + name);
+    if (p.vacuous !== undefined)
+      need(e, typeof p.vacuous === "boolean", "baseline.vacuous:" + name);
+    for (const f of Array.isArray(p.findings) ? p.findings : []) {
+      if (!record(f)) {
+        e.push("baseline.finding:" + name);
+        continue;
+      }
+      need(e, snapshotFinding(f), "baseline.finding:" + name);
+    }
+  }
+  return e;
+}
+function validateBaselineResult(b) {
+  if (b === null) return [];
+  const e = [];
+  if (!record(b)) return ["baseline result"];
+  if (b.error !== undefined) {
+    need(e, text(b.error) && text(b.note), "baseline.error");
+    return e;
+  }
+  need(e, typeof b.wrote === "boolean", "baseline.wrote");
+  need(e, record(b.badge), "baseline.badge");
+  if (record(b.badge)) {
+    need(
+      e,
+      typeof b.badge.show === "boolean" &&
+        nullableText(b.badge.text) &&
+        nullableText(b.badge.detail) &&
+        [null, "worse", "better", "mixed", "neutral"].includes(
+          b.badge.direction,
+        ),
+      "baseline.badge.fields",
+    );
+  }
+  if (b.diff !== null) {
+    need(
+      e,
+      record(b.diff) && typeof b.diff.comparable === "boolean",
+      "baseline.diff",
+    );
+    if (record(b.diff)) {
+      for (const key of [
+        "added",
+        "removed",
+        "worsened",
+        "improved",
+        "updated",
+      ]) {
+        need(e, Array.isArray(b.diff[key]), "baseline.diff." + key);
+        for (const entry of Array.isArray(b.diff[key]) ? b.diff[key] : []) {
+          const at = "baseline.diff." + key;
+          if (!record(entry)) {
+            e.push(at + ".entry");
+            continue;
+          }
+          need(e, text(entry.name), at + ".name");
+          if (key === "added" || key === "removed") {
+            need(e, nullableText(entry.version), at + ".version");
+            continue;
+          }
+          need(
+            e,
+            nullableText(entry.versionFrom) &&
+              nullableText(entry.versionTo) &&
+              typeof entry.versionChanged === "boolean" &&
+              verdicts.includes(entry.verdictFrom) &&
+              verdicts.includes(entry.verdictTo) &&
+              text(entry.reason),
+            at + ".fields",
+          );
+          for (const field of ["newFindings", "goneFindings"]) {
+            need(
+              e,
+              Array.isArray(entry[field]) &&
+                entry[field].every(snapshotFinding),
+              at + "." + field,
+            );
+          }
+          need(
+            e,
+            Array.isArray(entry.changedFindings) &&
+              entry.changedFindings.every(
+                (c) =>
+                  record(c) && snapshotFinding(c.from) && snapshotFinding(c.to),
+              ),
+            at + ".changedFindings",
+          );
+        }
+      }
+      for (const key of ["dshVersionFrom", "dshVersionTo", "reason"])
+        need(e, nullableText(b.diff[key]), "baseline.diff." + key);
+      need(
+        e,
+        typeof b.diff.dshVersionChanged === "boolean",
+        "baseline.diff.dshVersionChanged",
+      );
+    }
+  }
+  return e;
+}
+function validateReportBody(body) {
+  const e = [];
+  if (!record(body)) return ["report"];
+  need(
+    e,
+    body.schemaVersion === REPORT_SCHEMA && body.kind === REPORT_KIND,
+    "report.schemaVersion/kind",
+  );
+  need(e, typeof body.ok === "boolean", "report.ok");
+  need(e, nullableText(body.toolVersion), "report.toolVersion");
+  need(e, record(body.inputs), "report.inputs");
+  if (body.ok === false) {
+    need(e, body.exitCode === 3 && text(body.error), "report.error/exitCode");
+    return e;
+  }
+  need(e, body.error === null, "report.error");
+  need(e, nullableText(body.dshVersion), "report.dshVersion");
+  e.push(...validateObservation(body.observation));
+  if (
+    record(body.observation) &&
+    body.observation.bound &&
+    body.observation.usable
+  ) {
+    const o = body.observation;
+    if (text(body.dshVersion) && text(o.dshVersion))
+      need(
+        e,
+        o.dshVersion === body.dshVersion,
+        "observation/report.dshVersion",
+      );
+    if (text(body.inputs?.nodeModules) && text(o.profileId))
+      need(
+        e,
+        pathIdentity(o.profileId) === pathIdentity(body.inputs.nodeModules),
+        "observation/report.profileId",
+      );
+  }
+  e.push(...validateBaselineResult(body.baseline));
+  const summary = body.summary,
+    plugins = body.plugins;
+  if (!record(summary) || !record(plugins))
+    return [...e, "report.summary/plugins"];
+  for (const key of [...verdicts, "limited", "vacuousOk"])
+    need(e, integer(summary[key]), "summary." + key);
+  const counts = {
+    ok: 0,
+    partial: 0,
+    broken: 0,
+    unknown: 0,
+    limited: 0,
+    vacuousOk: 0,
+  };
+  for (const [name, p] of Object.entries(plugins)) {
+    if (!record(p)) {
+      e.push("plugin:" + name);
+      continue;
+    }
+    need(
+      e,
+      p.name === name &&
+        nullableText(p.version) &&
+        verdicts.includes(p.verdict),
+      "plugin.identity/verdict:" + name,
+    );
+    need(e, typeof p.vacuous === "boolean", "plugin.vacuous:" + name);
+    if (verdicts.includes(p.verdict)) counts[p.verdict]++;
+    if (p.vacuous && p.verdict === "ok") counts.vacuousOk++;
+    const c = p.coverage;
+    need(
+      e,
+      record(c) &&
+        ["complete", "limited"].includes(c.status) &&
+        integer(c.verifiedCalls) &&
+        strings(c.limitations),
+      "plugin.coverage:" + name,
+    );
+    if (c?.status === "limited") counts.limited++;
+    for (const key of [
+      "findings",
+      "checked",
+      "clientSide",
+      "filtered",
+      "abstained",
+      "runtimeFacilities",
+    ])
+      need(e, Array.isArray(p[key]), "plugin." + key + ":" + name);
+    if (Array.isArray(p.findings))
+      for (const f of p.findings)
+        e.push(...validateFinding(f).map((x) => name + ":" + x));
+    need(e, coherentVerdict(p), "plugin.verdict/findings:" + name);
+    if (record(c) && integer(c.verifiedCalls))
+      need(
+        e,
+        p.vacuous === (p.verdict === "ok" && c.verifiedCalls === 0),
+        "plugin.vacuous/coverage:" + name,
+      );
+    if (record(c) && strings(c.limitations) && Array.isArray(p.clientSide))
+      need(
+        e,
+        (c.status === "limited") ===
+          (c.limitations.length > 0 ||
+            p.clientSide.length > 0 ||
+            p.vacuous === true),
+        "plugin.coverage/status:" + name,
+      );
+    need(e, record(p.resolved), "plugin.resolved:" + name);
+    if (record(p.resolved))
+      for (const [service, value] of Object.entries(p.resolved))
+        need(
+          e,
+          checkedEntry(value) && value.service === service,
+          "plugin.resolved.entry:" + name + "." + service,
+        );
+    for (const [key, valid] of [
+      ["checked", checkedEntry],
+      ["clientSide", (v) => record(v) && text(v.service) && text(v.note)],
+      [
+        "filtered",
+        (v) => record(v) && text(v.service) && text(v.method) && text(v.reason),
+      ],
+      ["abstained", (v) => record(v) && text(v.service) && text(v.basis)],
+      ["runtimeFacilities", (v) => record(v) && text(v.name) && text(v.reason)],
+    ])
+      if (Array.isArray(p[key]))
+        need(e, p[key].every(valid), "plugin." + key + ".entry:" + name);
+  }
+  for (const key of Object.keys(counts))
+    need(e, counts[key] === summary[key], "summary.count:" + key);
+  need(e, body.exitCode === exitCodeForSummary(summary), "report.exitCode");
+  need(
+    e,
+    record(body.extraction) &&
+      typeof body.extraction.scanComplete === "boolean" &&
+      Array.isArray(body.extraction.diagnostics) &&
+      Array.isArray(body.extraction.manifests),
+    "report.extraction",
+  );
+  return e;
+}
+function assertReportBody(body) {
+  const errors = validateReportBody(body);
+  if (errors.length) throw new Error("报告契约不匹配: " + errors.join(", "));
+  return body;
+}
+function sealReportBody(input) {
+  const observation = input.observation || {};
+  const plugins = Object.fromEntries(
+    Object.entries(input.plugins || {}).map(([name, p]) => [
+      name,
+      {
+        ...p,
+        findings: p.findings.map((f) => ({
+          ...f,
+          location: f.location ?? null,
+        })),
+      },
+    ]),
+  );
+  return assertReportBody({
+    ...input,
+    schemaVersion: REPORT_SCHEMA,
+    kind: REPORT_KIND,
+    ok: true,
+    error: null,
+    exitCode: exitCodeForSummary(input.summary),
+    summary: { limited: 0, vacuousOk: 0, ...input.summary },
+    plugins,
+    observation: {
+      profileId: null,
+      dshVersion: null,
+      probedAt: null,
+      ...observation,
+    },
+    baseline: input.baseline ?? null,
+  });
+}
+function failureEnvelope(error, options = {}) {
+  const report = createFailure(error, {
+    toolVersion: options.toolVersion ?? null,
+    inputs: options.report?.inputs || {},
+  });
+  return {
+    ...options,
+    schemaVersion: REPORT_SCHEMA,
+    kind: ENVELOPE_KIND,
+    ok: false,
+    error: report.error,
+    exitCode: 3,
+    toolVersion: report.toolVersion,
+    baseline: null,
+    report,
+  };
+}
+function validateEnvelope(data) {
+  if (
+    !record(data) ||
+    data.schemaVersion !== REPORT_SCHEMA ||
+    data.kind !== ENVELOPE_KIND
+  )
+    return ["envelope.schemaVersion/kind"];
+  const e = validateReportBody(data.report);
+  need(
+    e,
+    typeof data.ok === "boolean" && data.ok === data.report?.ok,
+    "envelope.ok",
+  );
+  need(e, data.exitCode === data.report?.exitCode, "envelope.exitCode");
+  need(e, data.error === data.report?.error, "envelope.error");
+  need(
+    e,
+    data.toolVersion === data.report?.toolVersion,
+    "envelope.toolVersion",
+  );
+  need(
+    e,
+    JSON.stringify(data.baseline) ===
+      JSON.stringify(data.report?.baseline ?? null),
+    "envelope.baseline",
+  );
+  return e;
+}
+function assertEnvelope(data) {
+  const errors = validateEnvelope(data);
+  if (errors.length) throw new Error("报告契约不匹配: " + errors.join(", "));
+  return data;
+}
+
+return { assertEnvelope: assertEnvelope };
+    })();
+    // END GENERATED REPORT CONTRACT
+
     var React = require("react");
 
     var SLOT = "settings.plugins.tab";
     var LABEL = "兼容性";
     var ROUTE = "/plugin-compat-check/report";
-    // C3：单插件视图的两个槽位。实测（Plan.md §5 C3）：
+    // C3：单插件视图的两个槽位。实测（docs/Plan.md §5 C3）：
     //   - 详情页不是「抽屉」，是侧栏插件面板**换了 React 视图状态**：
     //     侧栏轨道按钮 [class*="panelRow"][aria-label="插件"] → 卡片标题
     //     button[class*="cardOpen"][aria-label="查看 <名字>"] → 返回用 button[class*="crumb"]。
@@ -56,10 +556,11 @@ window.__ModuleLoader__.load({
       "host-method-missing": "方法缺失",
       "unprovided-dependency": "无人提供的依赖",
       "declaration-mismatch": "声明与实测不符",
+      "declared-incompatible": "版本声明不支持",
     };
 
     // 渲染侧标记：只在我们的组件体里设置。页面上出现同名文字**不能**证明
-    // 是我们渲染的，这个标记能 —— 验收要经得起这个追问（Plan.md §7.2.1 ③）。
+    // 是我们渲染的，这个标记能 —— 验收要经得起这个追问（docs/Plan.md §7.2.1 ③）。
     function mark(extra) {
       try {
         var prev = window.__COMPAT_CHECK__ || {};
@@ -91,6 +592,14 @@ window.__ModuleLoader__.load({
     }
 
     /** C3 · 详情页 section：这个插件的完整结论 + 每条发现的证据 */
+    function acceptPayload(data) {
+      try { return ReportContract.assertEnvelope(data); }
+      catch (error) {
+        console.warn('[dsh-plugin-compat-check] invalid report', String(error && error.message || error));
+        throw new Error('无法读取体检报告：报告格式或版本不受支持，请刷新页面并确认宿主与插件版本一致。');
+      }
+    }
+
     function useCompatibility() {
       var state = React.useState({ phase: "loading", data: null, error: null });
       var value = state[0];
@@ -109,6 +618,7 @@ window.__ModuleLoader__.load({
               return res.json();
             })
             .then(function (data) {
+              data = acceptPayload(data);
               if (!alive.current) return;
               set({ phase: "done", data: data, error: null });
             })
@@ -199,7 +709,9 @@ window.__ModuleLoader__.load({
           f.certainty !== "certain"
             ? React.createElement("span", { style: styles.suspect, title: "没有运行时面，只能靠官方目录推断" }, " [疑似]")
             : null,
-          f.impact ? React.createElement("div", { style: styles.dim }, f.impact) : null);
+          f.impact ? React.createElement("div", { style: styles.dim },
+            (f.impactBasis === "inferred" ? "影响（推断，非实测）：" : "影响：") + f.impact) : null,
+          f.basis ? React.createElement("div", { style: styles.dim }, "依据：" + f.basis) : null);
       }));
     }
 
@@ -289,7 +801,7 @@ window.__ModuleLoader__.load({
     /**
      * C4 · 基线角标：回答「**和上次比变了没有**」，并给出方向。
      *
-     * 规则是 Plan.md §2 第 5 题的落地：**任何变化都打**，不只是变差。
+     * 规则是 docs/Plan.md §2 第 5 题的落地：**任何变化都打**，不只是变差。
      * 只有变差才亮会漏掉"某个插件被修好了、你可以放心留着了" —— 那同样是用户要知道的事。
      * 没有基线时**不打**角标，但要说清是「还没比过」而不是「没问题」。
      */
@@ -459,10 +971,11 @@ window.__ModuleLoader__.load({
               React.createElement("td", { style: styles.td }, React.createElement(Findings, { plugin: pl })));
           }))),
         React.createElement("div", { style: styles.note },
-          report.hasRuntimeSurface
-            ? "方法级判定依据：宿主运行时面（确定）。"
+          "工具版本：" + (data.toolVersion || "未知") + " · " + (report.summary.limited ? "部分证据尚未验证。 " : "") + (report.hasRuntimeSurface
+            ? "方法级判定依据：宿主运行时面；确定性以每条证据为准。"
             : "方法级判定依据：官方 API 目录（契约目录，不是运行时面）—— 因此方法级结论标为「疑似」。"
-              + "「疑似」不是缺陷，是诚实：判不准时降级标注，而不是升格成确定。"),
+              + "「疑似」不是缺陷，是诚实：判不准时降级标注，而不是升格成确定。")),
+        React.createElement("div", { style: styles.note }, (report.observation && report.observation.notes || []).join("；")),
         React.createElement("div", { style: styles.note },
           "判定内核：" + (data.kernelDir || "?")
           + " · 体检对象：" + (data.nodeModules || "?") + "（" + (data.nodeModulesWhy || "?") + "）"
@@ -538,7 +1051,7 @@ window.__ModuleLoader__.load({
      * 注册一个槽位，并把结果**记在标记里**。
      *
      * 为什么要记账：注册失败必须是**响的**。静默失败会让人以为"这个槽位不渲染"，
-     * 而真相是"我们没注册上" —— 两者要查的方向完全不同。实测（Plan.md §5 C3）
+     * 而真相是"我们没注册上" —— 两者要查的方向完全不同。实测（docs/Plan.md §5 C3）
      * 三个 detail 槽位都真的渲染，所以一旦它们不出现，第一个该怀疑的是注册。
      */
     function registerSlot(ctx, slot, spec, Comp, tag) {

package/lib/host-resources.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/** Iterate without awaiting inactive fibers, and map only verified package identities. */
+export function loaderObservations(ctx, manifests, items = []) {
+  const rows = [],
+    unmapped = [];
+  const names = new Set(manifests.map((m) => m.name));
+  let loader;
+  try {
+    loader = ctx.get?.("loader", false) || ctx.loader;
+  } catch {}
+  if (!loader?.entries) return { rows, unmapped, available: false };
+  try {
+    let count = 0;
+    for (const entry of loader.entries()) {
+      if (count++ >= 20000) {
+        unmapped.push("(entry limit)");
+        break;
+      }
+      const opts = entry.options || {},
+        id = entry.id ?? opts.id;
+      const packageName =
+        [
+          entry.packageName,
+          opts.packageName,
+          opts.name,
+          items.find((i) => i.id === id)?.packageName,
+          id,
+        ].find((v) => typeof v === "string" && names.has(v)) || null;
+      const state =
+        ["PENDING", "LOADING", "ACTIVE", "FAILED", "DISPOSED", "UNLOADING"][
+          entry.fiber?.state
+        ] || "UNREADABLE";
+      if (!packageName) {
+        unmapped.push(String(id ?? "(unknown)"));
+        continue;
+      }
+      rows.push({
+        packageName,
+        id,
+        state,
+        disabled: entry.disabled === true,
+        group: opts.group === true,
+      });
+    }
+    return { rows, unmapped, available: true };
+  } catch {
+    return {
+      rows,
+      unmapped: [...unmapped, "(loader unreadable)"],
+      available: false,
+    };
+  }
+}
+
+/** Diagnostics are opt-in, user-owned and refuse symlink output. */
+export function privateDiagnostic(file, data) {
+  if (!file) return false;
+  const dir = path.dirname(file);
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(dir);
+    if (
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      (stat.mode & 0o077) !== 0 ||
+      (typeof process.getuid === "function" && stat.uid !== process.getuid())
+    )
+      throw new Error(
+        "Diagnostic directory must be private and owned by this user",
+      );
+    if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink())
+      throw new Error("Diagnostic output is a symlink");
+    const fd = fs.openSync(
+      file,
+      fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_TRUNC |
+        (fs.constants.O_NOFOLLOW || 0),
+      0o600,
+    );
+    try {
+      fs.writeFileSync(fd, JSON.stringify(data, null, 2) + "\n");
+    } finally {
+      fs.closeSync(fd);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}