@monster-orange/den 0.0.0-stage → 0.1.0

package/src/shared/environment-manager/dag.ts

@@ -0,0 +1,286 @@
+/**
+ * Dependency DAG for local service startup ordering.
+ *
+ * Reads `depends_on` from each service's .den.yml and produces a
+ * topologically sorted startup order (dependencies before dependents).
+ *
+ * depends_on entries are service addresses: "tasks-runner", "shop/api".
+ */
+
+import { readManifest } from "../manifest/read-manifest.js";
+import { depService, normalizeDep } from "../manifest/deps.js";
+import type { ServiceCatalog, WorkspaceConfig } from "../types/index.js";
+import {
+  parseAddress,
+  resolveServiceSource,
+  resolveDepAddress,
+} from "./workspaces.js";
+
+/**
+ * Read `depends_on` for one service address from its manifest.
+ * Returns [] if the manifest is absent or the service has no declared deps.
+ */
+function readDepsForAddress(
+  address: string,
+  catalog: ServiceCatalog,
+  workspace: WorkspaceConfig,
+  workspaceName: string,
+): string[] {
+  const resolved = resolveServiceSource(
+    address,
+    workspaceName,
+    workspace,
+    catalog,
+  );
+  if (!resolved) return [];
+  const { subsystem } = parseAddress(address, catalog);
+  const manifest = readManifest(resolved.repoPath);
+  const rawDeps = manifest?.services?.[subsystem]?.depends_on ?? [];
+  // Normalize bare repo deps to their entrypoint address ("files-api" →
+  // "files-api/api" when files-api declares entrypoint: api).
+  return rawDeps.map((dep) =>
+    resolveDepAddress(depService(dep), catalog, workspace, workspaceName),
+  );
+}
+
+/**
+ * Return the deps flagged with `wait: true` for one service address, resolved
+ * to canonical addresses. The workspace runner calls this before starting a
+ * service to decide which deps to block on (`waitForReady`).
+ */
+export function getWaitDeps(
+  address: string,
+  catalog: ServiceCatalog,
+  workspace: WorkspaceConfig,
+  workspaceName: string,
+): string[] {
+  const resolved = resolveServiceSource(
+    address,
+    workspaceName,
+    workspace,
+    catalog,
+  );
+  if (!resolved) return [];
+  const { subsystem } = parseAddress(address, catalog);
+  const manifest = readManifest(resolved.repoPath);
+  const rawDeps = manifest?.services?.[subsystem]?.depends_on ?? [];
+  return rawDeps
+    .map(normalizeDep)
+    .filter((d) => d.wait)
+    .map((d) =>
+      resolveDepAddress(d.service, catalog, workspace, workspaceName),
+    );
+}
+
+/**
+ * Expand an explicit start list with SAME-REPO `wait: true` dependencies whose
+ * health check is actively failing, deps-first.
+ *
+ * An explicit address (card ▶ up) runs only that address, while the exec
+ * runner blocks on its `wait: true` deps' HEALTH before starting it — and for
+ * a sibling subsystem, the thing that makes the dep healthy is the dep's own
+ * `up`, which nothing else will run. That inverted the order every manifest
+ * intends (init the dep, THEN wait) into a wait that could only time out.
+ *
+ * Cross-repo deps are deliberately not expanded: they belong to another
+ * system's lifecycle, and waiting is the correct posture there. Deps whose
+ * health is "ok" need nothing; "unknown" (no check / no manifest) cannot
+ * deadlock the wait because readiness skips it.
+ *
+ * Injected callbacks keep this pure: `repoOf`/`waitDepsOf` wrap the catalog
+ * and manifest lookups, `isFailing` wraps resolve + health check.
+ */
+export async function expandSameRepoWaitDeps(
+  ordered: string[],
+  deps: {
+    repoOf: (addr: string) => string;
+    waitDepsOf: (addr: string) => string[];
+    isFailing: (addr: string) => Promise<boolean>;
+    /**
+     * Canonical identity for an address — repo + subsystem, so two spellings
+     * of the SAME service collapse. Several address forms can name one service
+     * (a bare repo name vs `repo/entrypoint`, or a `repo/repo` dep against a
+     * manifest whose service key equals the repo name), and treating those as
+     * distinct would start it twice. Defaults to the address itself.
+     */
+    identityOf?: (addr: string) => string;
+  },
+): Promise<{ ordered: string[]; added: string[] }> {
+  const idOf = deps.identityOf ?? ((addr: string) => addr);
+  const expanded: string[] = [];
+  const queued = new Set<string>(); // identities, not raw addresses
+  // identity -> the CALLER's spelling of it. A hoisted dep must be emitted
+  // under the address the caller listed, not the manifest's spelling of the
+  // same service: downstream keys off the exact string (isPrimaryAddr in
+  // local-dev.html compares the full address), so substituting a dep-only
+  // spelling silently stops the live log auto-attaching.
+  const explicitAddr = new Map<string, string>();
+  for (const addr of ordered) {
+    const id = idOf(addr);
+    if (!explicitAddr.has(id)) explicitAddr.set(id, addr);
+  }
+
+  const addWithDeps = async (
+    addr: string,
+    stack: Set<string>,
+  ): Promise<void> => {
+    const id = idOf(addr);
+    if (queued.has(id) || stack.has(id)) return; // done / dep cycle
+    stack.add(id);
+    const repoName = deps.repoOf(addr);
+
+    // Filter BEFORE probing: an already-queued dep needs nothing, an in-stack
+    // dep is a cycle addWithDeps would bounce anyway, and a cross-repo dep is
+    // never expanded — none of them should cost a live health check.
+    const candidates = deps
+      .waitDepsOf(addr)
+      .filter(
+        (d) =>
+          !queued.has(idOf(d)) &&
+          !stack.has(idOf(d)) &&
+          deps.repoOf(d) === repoName,
+      );
+
+    // Two tiers, because ordering and adding are different questions:
+    //
+    //  - A dep ALREADY in the run list is hoisted regardless of health. Health
+    //    now says nothing about health later: on `restart` every listed service
+    //    is going down anyway, so leaving a currently-healthy dep after its
+    //    dependent means it gets torn down and recreated underneath a service
+    //    that has already been restarted against it. Hoisting is also free —
+    //    it needs no probe, which is why a whole-workspace start (where every
+    //    dep is listed) costs zero probes.
+    //  - A dep NOT in the run list is only pulled in when its health is
+    //    actively failing, so a start never quietly grows into services the
+    //    caller did not ask for.
+    const unlisted = candidates.filter((d) => !explicitAddr.has(idOf(d)));
+    // Probe concurrently — these are spawns/fetches, and doing them serially is
+    // what put several seconds of dead air before the first log line.
+    const failing = new Set(
+      (
+        await Promise.all(
+          unlisted.map(async (d) => ((await deps.isFailing(d)) ? d : null)),
+        )
+      ).filter((d): d is string => d !== null),
+    );
+    // Recurse in the manifest's declared order so the result is deterministic.
+    for (const depAddr of candidates) {
+      if (explicitAddr.has(idOf(depAddr)) || failing.has(depAddr)) {
+        await addWithDeps(depAddr, stack);
+      }
+    }
+
+    stack.delete(id);
+    queued.add(id);
+    expanded.push(explicitAddr.get(id) ?? addr);
+  };
+
+  for (const addr of ordered) await addWithDeps(addr, new Set());
+  return {
+    ordered: expanded,
+    added: expanded.filter((a) => !explicitAddr.has(idOf(a))),
+  };
+}
+
+/**
+ * Build the full dependency graph for the given seed addresses, following
+ * transitive dependencies that are also present in the catalog.
+ * Returns a map of address → direct dependency addresses.
+ */
+export function buildDependencyGraph(
+  seedAddresses: string[],
+  catalog: ServiceCatalog,
+  workspace: WorkspaceConfig,
+  workspaceName: string,
+): Map<string, string[]> {
+  const graph = new Map<string, string[]>();
+  const queue = [...seedAddresses];
+
+  while (queue.length > 0) {
+    const addr = queue.pop()!;
+    if (graph.has(addr)) continue;
+
+    const deps = readDepsForAddress(
+      addr,
+      catalog,
+      workspace,
+      workspaceName,
+    ).filter((d) => {
+      const { repoName } = parseAddress(d, catalog);
+      if (!catalog[repoName]) return false;
+      // Only follow deps present in the workspace (check both explicit subsystem
+      // address and bare repo-name key for mono-repo bare entries like "shop").
+      return !!(workspace.services[d] ?? workspace.services[repoName]);
+    });
+
+    graph.set(addr, deps);
+
+    for (const dep of deps) {
+      if (!graph.has(dep)) queue.push(dep);
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Topologically sort the dependency graph using Kahn's algorithm.
+ * Returns addresses in startup order: dependencies before dependents.
+ * Throws if a cycle is detected.
+ */
+export function topoSort(graph: Map<string, string[]>): string[] {
+  const reversedInDegree = new Map<string, number>();
+  const reversedEdges = new Map<string, string[]>();
+  for (const addr of graph.keys()) {
+    reversedInDegree.set(addr, 0);
+    reversedEdges.set(addr, []);
+  }
+  for (const [addr, deps] of graph.entries()) {
+    reversedInDegree.set(addr, deps.length);
+    for (const dep of deps) {
+      reversedEdges.get(dep)!.push(addr);
+    }
+  }
+
+  const ready: string[] = [];
+  for (const [addr, deg] of reversedInDegree.entries()) {
+    if (deg === 0) ready.push(addr);
+  }
+
+  const order: string[] = [];
+  while (ready.length > 0) {
+    const node = ready.shift()!;
+    order.push(node);
+    for (const dependent of reversedEdges.get(node) ?? []) {
+      const newDeg = (reversedInDegree.get(dependent) ?? 1) - 1;
+      reversedInDegree.set(dependent, newDeg);
+      if (newDeg === 0) ready.push(dependent);
+    }
+  }
+
+  if (order.length !== graph.size) {
+    const cycle = [...graph.keys()].filter((a) => !order.includes(a));
+    throw new Error(`Dependency cycle detected among: ${cycle.join(", ")}`);
+  }
+
+  return order;
+}
+
+/**
+ * Given seed service addresses, return the full startup order including
+ * transitive dependencies (deps first). Deps not in the catalog are ignored.
+ */
+export function resolveStartupOrder(
+  addresses: string[],
+  catalog: ServiceCatalog,
+  workspace: WorkspaceConfig,
+  workspaceName: string,
+): string[] {
+  const graph = buildDependencyGraph(
+    addresses,
+    catalog,
+    workspace,
+    workspaceName,
+  );
+  return topoSort(graph);
+}

package/src/shared/environment-manager/default-workspace.ts

@@ -0,0 +1,182 @@
+/**
+ * Default-workspace blueprint + seeding.
+ *
+ * `config/den.yml` `defaults.workspace` declares the out-of-the-box repo set,
+ * all managed. On a fresh clone (no local workspace) den offers — once —
+ * to seed the `default` workspace from it so `den graph` / `den up` show the
+ * full system graph immediately; `den init` (run in the den root) re-seeds.
+ * Catalog clone URLs derive as `<github_org>/<repo>`. Switch any repo to a local
+ * checkout with `den use-local <repo>`.
+ */
+import {
+  parseAddress,
+  readWorkspacesFile,
+  writeWorkspacesFile,
+} from "./workspaces.js";
+import { readCatalog, writeCatalog } from "./catalog.js";
+import { readDenConfig, requireGithubOrg } from "../den-config.js";
+import type { WorkspaceServiceEntry } from "../types/index.js";
+
+const DEFAULT_BRANCH = "main";
+
+export function defaultWorkspaceRepos(): string[] {
+  return readDenConfig().defaults?.workspace?.repos ?? [];
+}
+
+function defaultBranch(): string {
+  return readDenConfig().defaults?.workspace?.branch ?? DEFAULT_BRANCH;
+}
+
+function org(): string {
+  return requireGithubOrg();
+}
+
+/** True on a fresh clone: a blueprint exists but the `default` workspace is empty. */
+export function defaultWorkspaceNeedsSeeding(): boolean {
+  if (defaultWorkspaceRepos().length === 0) return false;
+  const def = readWorkspacesFile().workspaces["default"];
+  return !def || Object.keys(def.services ?? {}).length === 0;
+}
+
+/** Whether the `default` workspace already has services (so seeding would reset it). */
+export function defaultWorkspaceHasServices(): boolean {
+  const def = readWorkspacesFile().workspaces["default"];
+  return !!def && Object.keys(def.services ?? {}).length > 0;
+}
+
+/**
+ * Seed (or reset) the `default` workspace from the blueprint — every repo as a
+ * bare, first-class managed entry on `branch` — and ensure the catalog has
+ * clone URLs (`<org>/<repo>`, only filled where missing). Returns the seeded repos.
+ */
+export function seedDefaultWorkspace(): string[] {
+  const repos = defaultWorkspaceRepos();
+  const branch = defaultBranch();
+  // Team default for systems a fresh workspace should NOT auto-start (e.g.
+  // billing-api's `make up` opens an interactive Stripe tab). Personal after
+  // seeding — toggled per system in the web ⋮ menu.
+  const autostartOff = new Set(
+    readDenConfig().defaults?.workspace?.autostart_off ?? [],
+  );
+  const services: Record<string, WorkspaceServiceEntry> = {};
+  for (const repo of repos) {
+    services[repo] = {
+      mode: "managed",
+      branch,
+      ...(autostartOff.has(repo) ? { autostart: false } : {}),
+    };
+  }
+
+  const file = readWorkspacesFile();
+  file.workspaces.default = {
+    ...(file.workspaces.default ?? {}),
+    services,
+    seeded_repos: [...repos],
+  };
+  if (!file.active?.length) {
+    file.active = ["default"];
+    file.focus = "default";
+  }
+  writeWorkspacesFile(file);
+
+  const catalog = readCatalog();
+  const o = org();
+  for (const repo of repos) {
+    if (!catalog[repo]?.gh) catalog[repo] = { gh: `${o}/${repo}` };
+  }
+  writeCatalog(catalog);
+
+  return repos;
+}
+
+/**
+ * Converge an EXISTING `default` workspace on the blueprint. Seeding is
+ * one-shot, so a workspace seeded before a repo joined
+ * `defaults.workspace.repos` (tasks-api, say) would never gain it on its own.
+ * Adds each missing blueprint repo exactly as seeding would (bare
+ * managed entry on `branch`, team autostart default, catalog clone URL
+ * where absent) and returns the added names. No-op — and no file writes —
+ * when already converged, or when the `default` workspace is empty/missing:
+ * that state belongs to the seeding/declined flow, not top-up.
+ */
+/**
+ * Converge an EXISTING `default` workspace on the blueprint. Seeding is
+ * one-shot, so a workspace seeded before a repo joined
+ * `defaults.workspace.repos` (tasks-api, say) would never gain it on its own.
+ *
+ * Converges on blueprint DELTAS, not set difference: only repos that JOINED
+ * the blueprint since it was last applied (`seeded_repos`) are candidates, so
+ * a standard repo the user removed from the workspace stays removed. Presence
+ * is checked at REPO level (workspace keys may be `repo/subsystem`
+ * addresses), so a repo held as subsystem entries never gains a duplicate
+ * bare entry. Added repos get exactly what seeding writes: bare
+ * managed entry on `branch`, team autostart default, catalog clone
+ * URL where absent. Returns the added names.
+ *
+ * No-op — and no file writes once converged — when the blueprint is empty or
+ * the `default` workspace is empty/missing (that state belongs to the
+ * seeding/declined flow). Workspaces from before `seeded_repos` existed
+ * treat the whole blueprint as new once — the migration cannot distinguish
+ * "removed" from "seeded before the repo joined"; afterwards removals stick.
+ */
+export function topUpDefaultWorkspace(): string[] {
+  const repos = defaultWorkspaceRepos();
+  if (repos.length === 0) return [];
+
+  const file = readWorkspacesFile();
+  const def = file.workspaces["default"];
+  if (!def || Object.keys(def.services ?? {}).length === 0) return [];
+
+  const applied = new Set(def.seeded_repos ?? []);
+  const catalog = readCatalog();
+  const present = new Set(
+    Object.keys(def.services).map((k) => parseAddress(k, catalog).repoName),
+  );
+  const branch = defaultBranch();
+  const autostartOff = new Set(
+    readDenConfig().defaults?.workspace?.autostart_off ?? [],
+  );
+
+  const added: string[] = [];
+  for (const repo of repos) {
+    if (applied.has(repo) || present.has(repo)) continue;
+    def.services[repo] = {
+      mode: "managed",
+      branch,
+      ...(autostartOff.has(repo) ? { autostart: false } : {}),
+    };
+    added.push(repo);
+  }
+
+  const blueprintChanged =
+    def.seeded_repos?.length !== repos.length ||
+    repos.some((r, i) => def.seeded_repos?.[i] !== r);
+  if (added.length === 0 && !blueprintChanged) return [];
+
+  def.seeded_repos = [...repos];
+  writeWorkspacesFile(file);
+
+  if (added.length > 0) {
+    const o = org();
+    for (const repo of added) {
+      if (!catalog[repo]?.gh) catalog[repo] = { gh: `${o}/${repo}` };
+    }
+    writeCatalog(catalog);
+  }
+
+  return added;
+}
+
+/**
+ * Persist an empty `default` workspace so the one-time auto-seed prompt isn't
+ * asked again after the user declines it.
+ */
+export function markDefaultWorkspaceDeclined(): void {
+  const file = readWorkspacesFile();
+  file.workspaces.default = file.workspaces.default ?? { services: {} };
+  if (!file.active?.length) {
+    file.active = ["default"];
+    file.focus = "default";
+  }
+  writeWorkspacesFile(file);
+}

package/src/shared/environment-manager/derivation/alias.ts

@@ -0,0 +1,90 @@
+/**
+ * Alias normalization for dependency derivation.
+ *
+ * Service references in code/config use many spellings — `shop-api`, `backend`,
+ * `shop.backend`, `files-sdk`, `job-runner`, … — that all point at one
+ * canonical repo-system. The alias map (built-in defaults merged with
+ * `config/den.yml` `graph.aliases`) collapses those tokens to repo names,
+ * and its keys define the universe of known repo-systems.
+ */
+
+import type { GraphConfig } from "../../den-config.js";
+
+/**
+ * Built-in topology: none. Den ships no repo map of its own; the graph's
+ * repo-systems come from `config/den.yml` `graph.aliases`.
+ */
+export const DEFAULT_ALIASES: Record<string, string[]> = {};
+
+export interface AliasResolver {
+  /** Canonical repo-system names known to the graph. */
+  knownRepos: Set<string>;
+  /** The shared local-infra repo (`graph.infra.repo`), or null. */
+  infraRepo: string | null;
+  /** `graph.infra.signals`, compiled. */
+  infraSignals: RegExp[];
+  /** Resolve a raw token to a canonical repo name, or null if unknown. */
+  resolve(token: string): string | null;
+  /**
+   * Repos that are EVENT SINKS — you publish events to them (EventBridge) rather
+   * than call them synchronously. Detected by a `*-events` alias token (e.g.
+   * notes-api's `notes-events` SDK). Edges into these are reclassified to
+   * `event` so producer→sink flows show as events, not http.
+   */
+  eventSinks: Set<string>;
+  /** GitHub orgs whose Go modules count as SDK imports (`graph.sdk_orgs`). */
+  sdkOrgs: string[];
+  /** npm scopes, without `@`, whose packages count as SDK imports (`graph.npm_scopes`). */
+  npmScopes: string[];
+}
+
+/** Normalize a raw token to the form used for lookups. */
+function norm(token: string): string {
+  return token.trim().toLowerCase().replace(/_/g, "-");
+}
+
+/**
+ * Build a resolver from the built-in defaults merged with config overrides.
+ * For a canonical repo, config aliases are ADDED to the defaults (not replaced)
+ * so partial config entries don't drop built-in spellings.
+ */
+export function buildAliasResolver(
+  config?: GraphConfig,
+  extraRepos: Iterable<string> = [],
+): AliasResolver {
+  const merged: Record<string, string[]> = {};
+  for (const [repo, tokens] of Object.entries(DEFAULT_ALIASES)) {
+    merged[repo] = [...tokens];
+  }
+  for (const [repo, tokens] of Object.entries(config?.aliases ?? {})) {
+    merged[repo] = [...(merged[repo] ?? []), ...tokens];
+  }
+  // Every catalogued repo is a graph node, alias or not: with no built-in
+  // topology, a repo known only to the catalog would otherwise never appear
+  // and any edge to it (graph.edges included) would be dropped.
+  for (const repo of extraRepos) merged[repo] ??= [];
+
+  const lookup = new Map<string, string>();
+  const eventSinks = new Set<string>();
+  for (const repo of Object.keys(merged)) {
+    // The canonical name and its bare-name fragments resolve to itself.
+    lookup.set(norm(repo), repo);
+    for (const token of merged[repo]) lookup.set(norm(token), repo);
+    // A `*-events` alias token marks an event sink (its SDK publishes events).
+    if ([repo, ...merged[repo]].some((t) => /-events$/.test(norm(t)))) {
+      eventSinks.add(repo);
+    }
+  }
+
+  return {
+    knownRepos: new Set(Object.keys(merged)),
+    infraRepo: config?.infra?.repo?.trim() || null,
+    infraSignals: (config?.infra?.signals ?? []).map((s) => new RegExp(s)),
+    resolve(token: string): string | null {
+      return lookup.get(norm(token)) ?? null;
+    },
+    eventSinks,
+    sdkOrgs: config?.sdk_orgs ?? [],
+    npmScopes: (config?.npm_scopes ?? []).map((s) => s.replace(/^@/, "")),
+  };
+}

package/src/shared/environment-manager/derivation/cache.ts

@@ -0,0 +1,97 @@
+/**
+ * Per-repo derivation cache.
+ *
+ * Discovery runs on every `den up`/`graph`, but a repo only needs re-parsing
+ * when its input files change. We fingerprint each repo's input file set by
+ * `mtime+size` (a cheap `stat`, no read) and cache the edges that scanning that
+ * repo produced. Warm runs are near-instant; the graph still always reflects
+ * current repo state. The cache is an optimization, never a source of truth —
+ * deleting it just forces a cold derive.
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { getDistRoot } from "../../paths.js";
+import type { DerivedEdge } from "./types.js";
+import { repoInputFiles } from "./scan.js";
+
+// Bump whenever derivation RULES change (signals, alias handling, edge
+// classification) — the fingerprint only tracks repo inputs, so without a
+// bump every clone keeps serving graphs derived under the old rules.
+const CACHE_VERSION = 3;
+const CACHE_PATH = path.join(
+  getDistRoot(),
+  "config",
+  "local",
+  ".graph-cache.json",
+);
+
+interface CacheEntry {
+  fingerprint: string;
+  edges: DerivedEdge[];
+}
+
+interface CacheFile {
+  version: number;
+  /** Keyed by `repoName@absoluteCheckoutPath` (a repo name is not unique across workspaces). */
+  repos: Record<string, CacheEntry>;
+}
+
+/** Stable fingerprint of a repo's input files (`mtime+size`, no content read). */
+export function repoFingerprint(repoPath: string): string {
+  const hash = crypto.createHash("sha1");
+  for (const abs of repoInputFiles(repoPath)) {
+    try {
+      const s = fs.statSync(abs);
+      hash.update(`${abs}:${s.mtimeMs}:${s.size}\n`);
+    } catch {
+      /* file vanished between listing and stat — ignore */
+    }
+  }
+  return hash.digest("hex");
+}
+
+export function readGraphCache(): CacheFile {
+  try {
+    const raw = fs.readFileSync(CACHE_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as CacheFile;
+    if (parsed.version !== CACHE_VERSION)
+      return { version: CACHE_VERSION, repos: {} };
+    return parsed;
+  } catch {
+    return { version: CACHE_VERSION, repos: {} };
+  }
+}
+
+export function writeGraphCache(cache: CacheFile): void {
+  try {
+    const dir = path.dirname(CACHE_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    // Temp-then-rename so a concurrent reader (another den up/graph) never
+    // observes a half-written cache file. Unique temp name avoids writer
+    // collisions; rename is atomic within the same directory/filesystem.
+    const tmp = path.join(
+      dir,
+      `.graph-cache.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`,
+    );
+    try {
+      fs.writeFileSync(tmp, JSON.stringify(cache), "utf-8");
+      fs.renameSync(tmp, CACHE_PATH);
+    } catch (err) {
+      // Don't leave an orphaned temp file behind when the write/rename fails.
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        /* ignore cleanup failure */
+      }
+      throw err;
+    }
+  } catch {
+    /* cache is best-effort — never fail a command because it couldn't write */
+  }
+}
+
+export function emptyCache(): CacheFile {
+  return { version: CACHE_VERSION, repos: {} };
+}