chainlesschain 0.162.149 → 0.162.150

package/src/lib/memory-manager.js

@@ -7,7 +7,7 @@
 
 import fs from "fs";
 import path from "path";
-import { likePrefix } from "./sql-like.js";
+import { likePrefix, escapeLike } from "./sql-like.js";
 
 /**
  * Atomically write a UTF-8 file: a crash mid-write must not truncate MEMORY.md
@@ -98,12 +98,14 @@ export function searchMemory(db, query, options = {}) {
   if (!query || !query.trim()) return [];
 
   const limit = Math.max(1, parseInt(options.limit) || 20);
-  const pattern = `%${query}%`;
+  // Escape LIKE wildcards so a query containing % / _ is matched literally
+  // rather than as a wildcard (`search "%"` would otherwise match every entry).
+  const pattern = `%${escapeLike(query)}%`;
 
   return db
     .prepare(
       `SELECT * FROM memory_entries
-       WHERE content LIKE ?
+       WHERE content LIKE ? ESCAPE '\\'
        ORDER BY importance DESC, created_at DESC
        LIMIT ?`,
     )

package/src/lib/nostr-bridge.js

@@ -59,6 +59,59 @@ export function ensureNostrTables(db) {
   `);
 }
 
+/**
+ * Rehydrate the module-level _relays/_events Maps from the persisted
+ * nostr_relays/nostr_events tables. The `cc` CLI runs every command in a
+ * fresh process, so without this the Maps are empty on read and a relay/event
+ * added in a prior invocation is invisible (`cc nostr relays`/`events` show
+ * nothing; `dm-decrypt` can't find the DM). Call after ensureNostrTables(db).
+ * (_keypairs/_didMappings are intentionally ephemeral — no DB table.)
+ */
+export function loadFromDb(db) {
+  if (!db) return 0;
+  _relays.clear();
+  _events.clear();
+
+  const relayRows = db.prepare(`SELECT * FROM nostr_relays`).all();
+  for (const row of relayRows) {
+    _relays.set(row.id, {
+      id: row.id,
+      url: row.url,
+      status: row.status,
+      lastConnected: row.last_connected ?? null,
+      eventCount: row.event_count ?? 0,
+      readEnabled: !!row.read_enabled,
+      writeEnabled: !!row.write_enabled,
+    });
+  }
+
+  const eventRows = db.prepare(`SELECT * FROM nostr_events`).all();
+  for (const row of eventRows) {
+    let tags = [];
+    try {
+      tags = row.tags ? JSON.parse(row.tags) : [];
+    } catch {
+      tags = [];
+    }
+    _events.set(row.id, {
+      id: row.id,
+      pubkey: row.pubkey,
+      kind: row.kind,
+      content: row.content,
+      tags,
+      sig: row.sig ?? "",
+      // write side stores createdAt as unix seconds; the column is an ISO
+      // string — convert back so the two process paths agree.
+      createdAt: row.created_at
+        ? Math.floor(new Date(row.created_at).getTime() / 1000)
+        : null,
+      relayUrl: row.relay_url ?? null,
+    });
+  }
+
+  return _relays.size + _events.size;
+}
+
 /* ── Relay Management ─────────────────────────────────────── */
 
 export function listRelays() {

package/src/lib/permission-engine.js

@@ -275,6 +275,24 @@ export function revokePermission(db, userDid, permission) {
   return result.changes > 0;
 }
 
+/**
+ * Is a grant still active given its stored `expires_at`?
+ *
+ * The previous check compared `expires_at > now` as ISO STRINGS. That is
+ * fail-open on unvalidated input: an unpadded date ("2026-7-5") or any
+ * non-numeric-leading garbage ("next year") sorts lexicographically AFTER a
+ * canonical `now` ('7'/'n' > '0'/'2'), so an already-expired or malformed
+ * time-limited grant silently became a PERMANENT grant. Compare numerically and
+ * treat an unparseable expiry as expired (fail closed) so a typo can never widen
+ * access. A null/empty `expires_at` means no expiry.
+ */
+function _grantActive(expiresAt, nowMs) {
+  if (!expiresAt) return true;
+  const t = Date.parse(expiresAt);
+  if (Number.isNaN(t)) return false;
+  return t > nowMs;
+}
+
 /**
  * Get all roles and direct permissions for a user.
  */
@@ -287,15 +305,15 @@ export function getUserPermissions(db, userDid) {
     .all(userDid);
 
   // Filter out expired grants
-  const now = new Date().toISOString();
-  const grants = allGrants.filter((g) => !g.expires_at || g.expires_at > now);
+  const nowMs = Date.now();
+  const grants = allGrants.filter((g) => _grantActive(g.expires_at, nowMs));
 
   // Get direct permissions (not expired)
   const allDirectPerms = db
     .prepare("SELECT * FROM rbac_direct_permissions WHERE user_did = ?")
     .all(userDid);
-  const directPerms = allDirectPerms.filter(
-    (d) => !d.expires_at || d.expires_at > now,
+  const directPerms = allDirectPerms.filter((d) =>
+    _grantActive(d.expires_at, nowMs),
   );
 
   // Collect all permissions by looking up each role

package/src/lib/plugin-runtime/__tests__/remote-source.test.js

@@ -0,0 +1,256 @@
+/**
+ * remote-source tests — resolving a plugin from a hosted registry/manifest URL,
+ * with private-token auth and an offline cache. `fetch` and fs are injected via
+ * `_deps` so nothing hits the network or the real disk.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  isRemoteSource,
+  validateRegistry,
+  resolvePluginEntry,
+  listRegistryPlugins,
+  resolveRegistryToken,
+  fetchRegistry,
+  resolveRemoteSource,
+  registryCachePath,
+  _deps,
+} from "../remote-source.js";
+
+const REGISTRY = {
+  name: "acme",
+  plugins: [
+    {
+      name: "toml-tools",
+      source: "https://github.com/x/toml.git",
+      ref: "v1.0.0",
+      version: "1.0.0",
+      description: "TOML LSP",
+      sha256: "abc123",
+    },
+    { name: "py-helpers", source: "owner/py-helpers" },
+  ],
+};
+
+/** A fake in-memory fs + fetch wired into _deps. */
+function install(fakes = {}) {
+  const files = new Map(fakes.files || []);
+  _deps.existsSync = (p) => files.has(String(p));
+  _deps.readFileSync = (p) => {
+    if (!files.has(String(p))) throw new Error("ENOENT");
+    return files.get(String(p));
+  };
+  _deps.writeFileSync = (p, text) => files.set(String(p), text);
+  _deps.mkdirSync = () => {};
+  if (fakes.fetch) _deps.fetch = fakes.fetch;
+  return files;
+}
+
+/** Build a fetch that returns JSON once, then throws (to test caching). */
+function okThenOffline(body) {
+  let calls = 0;
+  return vi.fn(async () => {
+    calls++;
+    if (calls === 1) {
+      return { ok: true, status: 200, text: async () => JSON.stringify(body) };
+    }
+    throw new Error("ECONNREFUSED");
+  });
+}
+
+let orig;
+beforeEach(() => {
+  orig = { ..._deps };
+  delete process.env.CC_PLUGIN_REGISTRY_TOKEN;
+});
+afterEach(() => {
+  Object.assign(_deps, orig);
+  vi.restoreAllMocks();
+  delete process.env.CC_PLUGIN_REGISTRY_TOKEN;
+});
+
+describe("isRemoteSource", () => {
+  it("recognizes http(s) .json URLs", () => {
+    expect(isRemoteSource("https://x.com/registry.json")).toBe(true);
+    expect(isRemoteSource("http://x.com/a/b.json?ref=1")).toBe(true);
+  });
+  it("rejects local dirs, git URLs, and owner/repo", () => {
+    expect(isRemoteSource("./plugins/foo")).toBe(false);
+    expect(isRemoteSource("https://github.com/x/foo.git")).toBe(false);
+    expect(isRemoteSource("owner/repo")).toBe(false);
+  });
+});
+
+describe("validateRegistry", () => {
+  it("accepts a multi-plugin index", () => {
+    expect(validateRegistry(REGISTRY).plugins).toHaveLength(2);
+  });
+  it("wraps a single-plugin manifest into a one-entry registry", () => {
+    const r = validateRegistry({
+      name: "solo",
+      source: "owner/solo",
+      ref: "v2",
+    });
+    expect(r.plugins).toEqual([
+      { name: "solo", source: "owner/solo", ref: "v2" },
+    ]);
+  });
+  it("rejects garbage and entries missing name/source", () => {
+    expect(() => validateRegistry(null)).toThrow(/not a JSON object/);
+    expect(() => validateRegistry({ foo: 1 })).toThrow(
+      /plugins.*array.*source/,
+    );
+    expect(() => validateRegistry({ plugins: [{ name: "x" }] })).toThrow(
+      /missing name\/source/,
+    );
+  });
+});
+
+describe("resolvePluginEntry", () => {
+  it("selects by name", () => {
+    expect(resolvePluginEntry(REGISTRY, "py-helpers").source).toBe(
+      "owner/py-helpers",
+    );
+  });
+  it("auto-selects the sole plugin when name omitted", () => {
+    const solo = { plugins: [REGISTRY.plugins[0]] };
+    expect(resolvePluginEntry(solo).name).toBe("toml-tools");
+  });
+  it("requires a name when the registry has many", () => {
+    expect(() => resolvePluginEntry(REGISTRY)).toThrow(/pick one with --name/);
+  });
+  it("lists options when the name is unknown", () => {
+    expect(() => resolvePluginEntry(REGISTRY, "nope")).toThrow(
+      /not found.*toml-tools, py-helpers/s,
+    );
+  });
+});
+
+describe("resolveRegistryToken", () => {
+  it("prefers an explicit token, then env, then per-host config", () => {
+    expect(
+      resolveRegistryToken("https://h/r.json", { token: "explicit" }),
+    ).toBe("explicit");
+    process.env.CC_PLUGIN_REGISTRY_TOKEN = "envtok";
+    expect(resolveRegistryToken("https://h/r.json", {})).toBe("envtok");
+    delete process.env.CC_PLUGIN_REGISTRY_TOKEN;
+    const config = { plugins: { registryTokens: { "priv.co": "cfgtok" } } };
+    expect(resolveRegistryToken("https://priv.co/r.json", { config })).toBe(
+      "cfgtok",
+    );
+    expect(
+      resolveRegistryToken("https://other.co/r.json", { config }),
+    ).toBeNull();
+  });
+});
+
+describe("fetchRegistry", () => {
+  it("fetches, validates, and caches; sends a bearer token when given", async () => {
+    const fetch = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify(REGISTRY),
+    }));
+    install({ fetch });
+    const { registry, fromCache } = await fetchRegistry("https://h/r.json", {
+      token: "t",
+      cacheDir: "/cache",
+    });
+    expect(fromCache).toBe(false);
+    expect(registry.plugins).toHaveLength(2);
+    const [, init] = fetch.mock.calls[0];
+    expect(init.headers.Authorization).toBe("Bearer t");
+  });
+
+  it("falls back to the offline cache when the network fails", async () => {
+    const fetch = okThenOffline(REGISTRY);
+    install({ fetch });
+    // 1st call populates the cache
+    await fetchRegistry("https://h/r.json", { cacheDir: "/cache" });
+    // 2nd call: network throws → served from cache
+    const { registry, fromCache } = await fetchRegistry("https://h/r.json", {
+      cacheDir: "/cache",
+    });
+    expect(fromCache).toBe(true);
+    expect(registry.plugins).toHaveLength(2);
+  });
+
+  it("throws on HTTP error with no cache", async () => {
+    const fetch = vi.fn(async () => ({
+      ok: false,
+      status: 404,
+      statusText: "Not Found",
+      text: async () => "",
+    }));
+    install({ fetch });
+    await expect(
+      fetchRegistry("https://h/missing.json", { cacheDir: "/cache" }),
+    ).rejects.toThrow(/HTTP 404/);
+  });
+
+  it("throws when offline and nothing is cached", async () => {
+    const fetch = vi.fn(async () => {
+      throw new Error("ENOTFOUND");
+    });
+    install({ fetch });
+    await expect(
+      fetchRegistry("https://h/r.json", { cacheDir: "/cache" }),
+    ).rejects.toThrow(/no offline cache/);
+  });
+});
+
+describe("resolveRemoteSource", () => {
+  it("resolves a named entry to a git source string with a #ref and carries sha256", async () => {
+    const fetch = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify(REGISTRY),
+    }));
+    install({ fetch });
+    const r = await resolveRemoteSource("https://h/r.json", {
+      name: "toml-tools",
+      cacheDir: "/cache",
+    });
+    expect(r.source).toBe("https://github.com/x/toml.git#v1.0.0");
+    expect(r.sha256).toBe("abc123");
+    expect(r.fromCache).toBe(false);
+  });
+
+  it("omits the #ref when the entry has none", async () => {
+    const fetch = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify(REGISTRY),
+    }));
+    install({ fetch });
+    const r = await resolveRemoteSource("https://h/r.json", {
+      name: "py-helpers",
+      cacheDir: "/cache",
+    });
+    expect(r.source).toBe("owner/py-helpers");
+    expect(r.ref).toBeNull();
+  });
+});
+
+describe("listRegistryPlugins", () => {
+  it("flattens entries for display", () => {
+    const rows = listRegistryPlugins(REGISTRY);
+    expect(rows.map((r) => r.name)).toEqual(["toml-tools", "py-helpers"]);
+    expect(rows[0]).toMatchObject({
+      version: "1.0.0",
+      ref: "v1.0.0",
+      description: "TOML LSP",
+    });
+  });
+});
+
+describe("registryCachePath", () => {
+  it("is stable and content-addressed by URL", () => {
+    const a = registryCachePath("https://h/r.json", "/cache");
+    const b = registryCachePath("https://h/r.json", "/cache");
+    const c = registryCachePath("https://h/OTHER.json", "/cache");
+    expect(a).toBe(b);
+    expect(a).not.toBe(c);
+    expect(a.endsWith(".json")).toBe(true);
+  });
+});

package/src/lib/plugin-runtime/install.js

@@ -320,6 +320,14 @@ export function uninstall(name, opts = {}) {
         `${name}@${opts.version} is not installed at ${scope} scope`,
       );
     }
+    // Capture the active version BEFORE removing, so we only repoint `.active`
+    // when the version we removed WAS the active one. Removing a NON-active
+    // version (e.g. cleaning up a newer version after rolling back to an older
+    // pinned one) must not silently change which version is active — the old
+    // code always rewrote `.active` to the newest remaining, so uninstalling an
+    // unrelated version could bump the user's pinned choice.
+    const removedWasActive =
+      getActiveVersion(name, { scope, cwd }) === opts.version;
     _deps.rmSync(dir, { recursive: true, force: true });
     removed.push(opts.version);
     // Repoint .active to the newest remaining version, or clear it.
@@ -333,7 +341,7 @@ export function uninstall(name, opts = {}) {
         recursive: true,
         force: true,
       });
-    } else if (_deps.existsSync(activeFile)) {
+    } else if (removedWasActive && _deps.existsSync(activeFile)) {
       _deps.writeFileSync(activeFile, remaining[0], "utf8");
     }
     return { removed };

package/src/lib/plugin-runtime/policy.js

@@ -43,7 +43,15 @@ export function loadManagedPluginPolicy(opts = {}) {
   const key = String(
     opts.managedSettingsFile || env.CC_MANAGED_SETTINGS || "<default>",
   );
-  if (_cache.has(key)) return _cache.get(key);
+  if (_cache.has(key)) {
+    const cached = _cache.get(key);
+    // A cached failure sentinel must re-throw on EVERY call — otherwise the
+    // first call fails closed but later callers get the truthy {__invalid}
+    // object, treat it as an empty policy, and silently bypass the org's
+    // deny/allow/requireSignedPlugins enforcement (fail-open).
+    if (cached && cached.__invalid) throw cached.__invalid;
+    return cached;
+  }
   let settings = null;
   try {
     const loaded = _deps.loadManagedSettings({

package/src/lib/plugin-runtime/remote-source.js

@@ -0,0 +1,240 @@
+/**
+ * Remote plugin sources — install from a hosted registry / manifest URL, not
+ * just a local dir or git URL (Phase 3 "远程 manifest" + "私有仓认证" + "离线
+ * seed cache" work items).
+ *
+ * A remote source is an `https?://…/*.json` document, in one of two shapes:
+ *
+ *   1. Registry index — many plugins, selected by name:
+ *      { "name": "acme-registry",
+ *        "plugins": [
+ *          { "name": "toml-tools", "source": "https://github.com/x/toml.git",
+ *            "ref": "v1.0.0", "version": "1.0.0", "description": "…", "sha256": "…" },
+ *          { "name": "py-helpers", "source": "owner/py-helpers" }
+ *        ] }
+ *
+ *   2. Single-plugin manifest — one plugin, no selection needed:
+ *      { "name": "toml-tools", "source": "https://github.com/x/toml.git", "ref": "v1.0.0" }
+ *
+ * The remote layer is an INDIRECTION: it resolves a name → a git source string
+ * that the existing installer (`installFromSource`) already knows how to clone.
+ * This keeps the sync install core untouched and avoids bundling a tarball
+ * extractor. Downloaded registry JSON is cached content-addressed so browsing /
+ * installing works OFFLINE, and a bearer token can gate a PRIVATE registry.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { getElectronUserDataDir } from "../paths.js";
+
+export const _deps = {
+  // Node 22+ global fetch; injectable for tests.
+  fetch: (...args) => globalThis.fetch(...args),
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  existsSync: fs.existsSync,
+  mkdirSync: fs.mkdirSync,
+};
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** True when `raw` looks like a remote registry/manifest URL (http(s) + .json). */
+export function isRemoteSource(raw) {
+  const s = String(raw || "").trim();
+  return /^https?:\/\//i.test(s) && /\.json(\?.*)?(#.*)?$/i.test(s);
+}
+
+/** Where a fetched registry is cached (content-addressed by its URL). */
+export function registryCachePath(url, cacheDir) {
+  const dir =
+    cacheDir || path.join(getElectronUserDataDir(), "plugin-registry-cache");
+  const hash = crypto
+    .createHash("sha256")
+    .update(String(url))
+    .digest("hex")
+    .slice(0, 32);
+  return path.join(dir, `${hash}.json`);
+}
+
+/**
+ * Resolve the bearer token for a registry host from (in order): explicit
+ * `opts.token`, `CC_PLUGIN_REGISTRY_TOKEN` env, or a per-host map in config
+ * (`config.plugins.registryTokens[host]`). Returns null if none — a public
+ * registry needs no token.
+ */
+export function resolveRegistryToken(url, { token, config } = {}) {
+  if (token) return token;
+  if (process.env.CC_PLUGIN_REGISTRY_TOKEN)
+    return process.env.CC_PLUGIN_REGISTRY_TOKEN;
+  try {
+    const host = new URL(url).host;
+    const map = config?.plugins?.registryTokens;
+    if (map && map[host]) return map[host];
+  } catch {
+    /* bad URL — handled by fetch */
+  }
+  return null;
+}
+
+/**
+ * GET a registry/manifest URL as JSON, with optional bearer auth. On success the
+ * body is written to the offline cache; on a network/HTTP failure we fall back
+ * to that cache (so a previously-seen registry still installs offline). Throws
+ * only when neither the network NOR the cache can produce a valid document.
+ *
+ * @returns {Promise<{ registry: object, fromCache: boolean }>}
+ */
+export async function fetchRegistry(url, opts = {}) {
+  const {
+    token,
+    cacheDir,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    allowCache = true,
+  } = opts;
+  const cachePath = registryCachePath(url, cacheDir);
+  const headers = { Accept: "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  let networkErr = null;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await _deps.fetch(url, {
+        headers,
+        redirect: "follow",
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      throw new Error(
+        `registry fetch failed: HTTP ${res.status} ${res.statusText || ""}`.trim(),
+      );
+    }
+    const text = await res.text();
+    const registry = validateRegistry(JSON.parse(text), url);
+    if (allowCache) writeCache(cachePath, text);
+    return { registry, fromCache: false };
+  } catch (err) {
+    networkErr = err;
+  }
+
+  // Network failed — try the offline cache.
+  if (allowCache && _deps.existsSync(cachePath)) {
+    try {
+      const text = _deps.readFileSync(cachePath, "utf8");
+      const registry = validateRegistry(JSON.parse(text), url);
+      return { registry, fromCache: true };
+    } catch {
+      /* cache unreadable — fall through to throw the network error */
+    }
+  }
+  throw new Error(
+    `could not fetch registry ${url}: ${networkErr ? networkErr.message : "unknown error"}` +
+      (allowCache ? " (no offline cache available)" : ""),
+  );
+}
+
+function writeCache(cachePath, text) {
+  try {
+    _deps.mkdirSync(path.dirname(cachePath), { recursive: true });
+    _deps.writeFileSync(cachePath, text, "utf8");
+  } catch {
+    /* caching is best-effort; a read-only cache dir must not break install */
+  }
+}
+
+/** Validate + normalize a fetched document into a registry object. Throws on garbage. */
+export function validateRegistry(doc, url = "") {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    throw new Error(`registry at ${url} is not a JSON object`);
+  }
+  if (Array.isArray(doc.plugins)) {
+    for (const p of doc.plugins) {
+      if (!p || typeof p !== "object" || !p.name || !p.source) {
+        throw new Error(
+          `registry at ${url} has a plugin entry missing name/source`,
+        );
+      }
+    }
+    return doc;
+  }
+  // Single-plugin manifest.
+  if (doc.source) {
+    return { plugins: [doc] };
+  }
+  throw new Error(
+    `registry at ${url} must have a "plugins" array or a top-level "source"`,
+  );
+}
+
+/** List installable entries from a registry (for `cc plugin search`). */
+export function listRegistryPlugins(registry) {
+  return (registry.plugins || []).map((p) => ({
+    name: p.name,
+    version: p.version || null,
+    source: p.source,
+    ref: p.ref || null,
+    description: p.description || "",
+  }));
+}
+
+/**
+ * Pick one plugin entry from a registry. When the registry has exactly one
+ * plugin, `name` is optional; otherwise it must match. Returns the entry, or
+ * throws with a helpful list.
+ */
+export function resolvePluginEntry(registry, name) {
+  const plugins = registry.plugins || [];
+  if (plugins.length === 0) throw new Error("registry has no plugins");
+  if (!name) {
+    if (plugins.length === 1) return plugins[0];
+    throw new Error(
+      `registry has ${plugins.length} plugins — pick one with --name <plugin>:\n  ` +
+        plugins.map((p) => p.name).join(", "),
+    );
+  }
+  const entry = plugins.find((p) => p.name === name);
+  if (!entry) {
+    throw new Error(
+      `plugin "${name}" not found in registry. Available:\n  ` +
+        plugins.map((p) => p.name).join(", "),
+    );
+  }
+  return entry;
+}
+
+/**
+ * Full resolution: fetch the registry (with auth + offline cache), select the
+ * entry, and return the git source string the existing installer consumes plus
+ * carry-through metadata (ref pins the checkout; sha256 becomes an install
+ * integrity check).
+ *
+ * @returns {Promise<{ source: string, ref: string|null, sha256: string|null,
+ *   entry: object, fromCache: boolean }>}
+ */
+export async function resolveRemoteSource(url, opts = {}) {
+  const token = resolveRegistryToken(url, opts);
+  const { registry, fromCache } = await fetchRegistry(url, { ...opts, token });
+  const entry = resolvePluginEntry(registry, opts.name);
+  // Carry a `#ref` on the source string so installFromSource pins the checkout,
+  // matching its existing `owner/repo#ref` / `url#ref` convention.
+  const source = entry.ref ? `${entry.source}#${entry.ref}` : entry.source;
+  return {
+    source,
+    ref: entry.ref || null,
+    sha256: entry.sha256 || null,
+    entry,
+    fromCache,
+  };
+}
+
+/** Best-effort local temp dir helper (kept here so tests can stub fs deps). */
+export function _tmpRoot() {
+  return os.tmpdir();
+}