@vellumai/assistant 0.8.11 → 0.8.12-staging.1

package/src/cli/lib/install-from-github.ts

@@ -40,6 +40,12 @@ import { promisify } from "node:util";
 
 import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  computeContentHash,
+  computeFingerprint,
+  type Fingerprint,
+  parseFingerprint,
+} from "./plugin-fingerprint.js";
 import {
   fetchMarketplaceEntries,
   MarketplaceFetchError,
@@ -389,11 +395,25 @@ export async function installPlugin(
     throw new PluginNotFoundError(name, ref, sourceLabel(source));
   }
 
-  // Record install provenance (source coordinates + resolved commit) as a
-  // hidden sidecar before the swap so it lands atomically with the files. The
-  // daemon loader enumerates plugin directories and reads each plugin's
-  // `package.json`, skipping dotfiles — so this never gets mistaken for code.
-  writeInstallManifest(stagingDir, name, source, ref, commit);
+  // Hash the materialized tree before the sidecar is written (so the sidecar
+  // never hashes itself) — the baseline `plugins inspect` uses to detect later
+  // local edits. The per-file fingerprint answers "which files changed"; the
+  // whole-tree content hash is a compact integrity signal mirroring skills.
+  const fingerprint = computeFingerprint(stagingDir, [INSTALL_META_FILENAME]);
+  const contentHash = computeContentHash(stagingDir, [INSTALL_META_FILENAME]);
+
+  // Record install provenance (source coordinates + resolved commit + content
+  // digests) as a sidecar before the swap so it lands atomically with the
+  // files. The external plugin loader only reads `package.json` and the
+  // `hooks/`/`tools/` dirs, so this JSON file is never mistaken for code.
+  writeInstallMeta(stagingDir, {
+    name,
+    source,
+    ref,
+    commit,
+    fingerprint,
+    contentHash,
+  });
 
   // Atomic-ish swap: rmSync + renameSync. On POSIX the rename itself is
   // atomic, so the only window where the target is absent is between the
@@ -412,8 +432,78 @@ export async function installPlugin(
 /** Cap on any single git invocation; a shallow fetch is well under this. */
 const GIT_TIMEOUT_MS = 120_000;
 
-/** Install-provenance sidecar written at the plugin root. */
-const INSTALL_MANIFEST_FILENAME = ".vellum-plugin.json";
+/**
+ * Install-provenance sidecar written at the plugin root. Named to match the
+ * skills' sidecar (`install-meta.json`, see `src/skills/install-meta.ts`) so
+ * both subsystems share one vocabulary. The external plugin loader only reads
+ * `package.json` and the `hooks/`/`tools/` surface dirs, so a plain JSON file
+ * at the root is ignored by it.
+ */
+export const INSTALL_META_FILENAME = "install-meta.json";
+
+/**
+ * Which catalog manages an installed plugin. Mirrors the skill origin values
+ * (`SkillInstallMeta.origin` in `src/skills/install-meta.ts`) so the two
+ * systems keep a consistent vocabulary. `"vellum"` denotes the first-party
+ * `marketplace.json`; the union widens as new sources are supported.
+ */
+export type InstallOrigin = "vellum";
+
+/** Resolved source coordinates recorded in the provenance sidecar. */
+export interface InstallMetaSource {
+  /** Source kind. Only `github` is written today. */
+  readonly kind: string;
+  readonly owner: string;
+  readonly repo: string;
+  /** Repo-relative directory holding the plugin root; absent = repo root. */
+  readonly path?: string;
+  /** Ref the install resolved through (the pinned commit SHA for marketplace installs). */
+  readonly ref: string;
+}
+
+/**
+ * Parsed contents of the `install-meta.json` provenance sidecar — what was
+ * installed, from where, and at exactly which commit. Read by
+ * {@link readInstallMeta} for provenance reporting (e.g. `plugins inspect`).
+ *
+ * The leading fields share names (and meaning) with the skills'
+ * `SkillInstallMeta`; everything below {@link InstallMeta.name} is the
+ * plugin-specific superset that the git-backed install needs.
+ */
+export interface InstallMeta {
+  /** Catalog the install is managed from. */
+  readonly origin: InstallOrigin;
+  /** ISO-8601 timestamp of when the install was materialized. */
+  readonly installedAt: string;
+  /** Principal that initiated the install, when known. */
+  readonly installedBy?: string;
+  /** Set by a backfill migration when provenance was reconstructed after the fact. */
+  readonly backfilledBy?: string;
+  /** Plugin `package.json` version at install time, when present. */
+  readonly version?: string;
+  /** Registry slug, recorded when it diverges from {@link InstallMeta.name}. */
+  readonly slug?: string;
+  /** `owner/repo` the install was sourced from. */
+  readonly sourceRepo?: string;
+  /**
+   * Whole-tree `v2:` content hash — a compact integrity signal using the same
+   * scheme as the skills' `contentHash`. Complements the per-file
+   * {@link InstallMeta.fingerprint}.
+   */
+  readonly contentHash?: string;
+
+  /** Install name. Matches the plugins directory and `plugins install <name>`. */
+  readonly name: string;
+  readonly source: InstallMetaSource;
+  /** Resolved commit SHA the source was cloned at; `null` when it could not be read at install time. */
+  readonly commit: string | null;
+  /**
+   * Per-file content digest of the materialized tree, captured at install
+   * time. `null` for older installs written before fingerprinting; callers
+   * then report local-modification state as unknown rather than clean.
+   */
+  readonly fingerprint: Fingerprint | null;
+}
 
 /**
  * Materialize an external plugin by shallow-cloning its repo at the pinned ref.
@@ -852,20 +942,59 @@ function pluginGitEnv(): NodeJS.ProcessEnv {
   return env;
 }
 
+/** Inputs for {@link writeInstallMeta}, resolved during a fresh install. */
+interface WriteInstallMetaParams {
+  readonly name: string;
+  readonly source: PluginFetchSource;
+  readonly ref: string;
+  readonly commit: string | null;
+  readonly fingerprint: Fingerprint;
+  readonly contentHash: string;
+}
+
+/**
+ * Read the `version` field from a staged plugin's `package.json`. Lenient — a
+ * missing or malformed manifest simply yields `undefined` so provenance is
+ * recorded without it rather than failing the install.
+ */
+function readStagedPackageVersion(stagingDir: string): string | undefined {
+  const pkgPath = join(stagingDir, "package.json");
+  if (!existsSync(pkgPath)) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (typeof parsed === "object" && parsed !== null) {
+      const version = (parsed as Record<string, unknown>).version;
+      if (typeof version === "string" && version.length > 0) return version;
+    }
+  } catch {
+    // fall through to undefined
+  }
+  return undefined;
+}
+
 /**
- * Write the install-provenance sidecar into the staged plugin root, recording
- * the resolved source coordinates and commit so we can later report or verify
- * exactly what is installed. Hidden (dot-prefixed) so the daemon loader, which
- * skips dotfiles, never mistakes it for plugin code.
+ * Write the `install-meta.json` provenance sidecar into the staged plugin root,
+ * recording the resolved source coordinates, commit, and content digests so we
+ * can later report or verify exactly what is installed. The schema is an
+ * equal-name superset of the skills' `SkillInstallMeta`.
  */
-function writeInstallManifest(
+function writeInstallMeta(
   stagingDir: string,
-  name: string,
-  source: PluginFetchSource,
-  ref: string,
-  commit: string | null,
+  {
+    name,
+    source,
+    ref,
+    commit,
+    fingerprint,
+    contentHash,
+  }: WriteInstallMetaParams,
 ): void {
-  const manifest = {
+  const meta: InstallMeta = {
+    origin: "vellum",
+    installedAt: new Date().toISOString(),
+    version: readStagedPackageVersion(stagingDir),
+    sourceRepo: `${source.owner}/${source.repo}`,
+    contentHash,
     name,
     source: {
       kind: "github",
@@ -874,15 +1003,79 @@ function writeInstallManifest(
       path: source.rootPath || undefined,
       ref,
     },
-    commit: commit ?? undefined,
-    installedAt: new Date().toISOString(),
+    commit,
+    fingerprint,
   };
   writeFileSync(
-    join(stagingDir, INSTALL_MANIFEST_FILENAME),
-    `${JSON.stringify(manifest, null, 2)}\n`,
+    join(stagingDir, INSTALL_META_FILENAME),
+    `${JSON.stringify(meta, null, 2)}\n`,
   );
 }
 
+/**
+ * Read the install-provenance sidecar from an installed plugin's root.
+ *
+ * Lenient by design — a missing, unreadable, or malformed sidecar yields
+ * `null` rather than throwing, mirroring {@link ./list-installed-plugins}.
+ * Older or manually-copied installs that predate the sidecar simply report no
+ * provenance. The resolved commit is the authoritative record of which bytes
+ * are installed, so callers (e.g. `plugins inspect`) can compare it against the
+ * marketplace's current pin to detect drift.
+ */
+export function readInstallMeta(pluginDir: string): InstallMeta | null {
+  const metaPath = join(pluginDir, INSTALL_META_FILENAME);
+  if (!existsSync(metaPath)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(metaPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const src = obj.source;
+  if (typeof src !== "object" || src === null || Array.isArray(src)) {
+    return null;
+  }
+  const source = src as Record<string, unknown>;
+  if (
+    typeof obj.name !== "string" ||
+    typeof source.owner !== "string" ||
+    typeof source.repo !== "string" ||
+    typeof source.ref !== "string"
+  ) {
+    return null;
+  }
+
+  const optionalString = (value: unknown): string | undefined =>
+    typeof value === "string" ? value : undefined;
+
+  return {
+    origin: "vellum",
+    installedAt: typeof obj.installedAt === "string" ? obj.installedAt : "",
+    installedBy: optionalString(obj.installedBy),
+    backfilledBy: optionalString(obj.backfilledBy),
+    version: optionalString(obj.version),
+    slug: optionalString(obj.slug),
+    sourceRepo: optionalString(obj.sourceRepo),
+    contentHash: optionalString(obj.contentHash),
+    name: obj.name,
+    source: {
+      kind: typeof source.kind === "string" ? source.kind : "github",
+      owner: source.owner,
+      repo: source.repo,
+      path: typeof source.path === "string" ? source.path : undefined,
+      ref: source.ref,
+    },
+    commit: typeof obj.commit === "string" ? obj.commit : null,
+    fingerprint: parseFingerprint(obj.fingerprint),
+  };
+}
+
 /**
  * Recursively copy a curated adapter stub directory via the GitHub Contents API.
  *

package/src/cli/lib/list-installed-plugins.ts

@@ -12,12 +12,7 @@
  * and we want both surfaces to agree on what's present.
  */
 
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-} from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
@@ -81,6 +76,22 @@ export function listInstalledPlugins(
   return entries.map((name) => readPluginEntry(pluginsDir, name));
 }
 
+/**
+ * Read a single installed plugin entry by name, or `null` when no directory
+ * for it exists under the workspace plugins directory. Parses leniently like
+ * {@link listInstalledPlugins} — a malformed `package.json` surfaces as an
+ * `issues` entry rather than throwing.
+ */
+export function readInstalledPlugin(
+  name: string,
+  opts: ListInstalledPluginsOptions = {},
+): InstalledPluginInfo | null {
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+  if (!existsSync(target) || !statSync(target).isDirectory()) return null;
+  return readPluginEntry(pluginsDir, name);
+}
+
 function readPluginEntry(
   pluginsDir: string,
   name: string,

package/src/cli/lib/plugin-artifact.ts

@@ -0,0 +1,103 @@
+/**
+ * Parse a plugin's prebuilt client-artifact descriptor from its
+ * `package.json` `vellum.artifact` block.
+ *
+ * Some plugins ship a native companion the assistant cannot build itself —
+ * e.g. a macOS app whose Swift toolchain is absent from the Linux container
+ * the daemon runs in. Those plugins publish a prebuilt, author-signed binary
+ * out-of-band (a GitHub Release) and point at it from their manifest:
+ *
+ *     "vellum": {
+ *       "artifact": {
+ *         "url": "https://github.com/owner/repo/releases/download/v1.0.0/App.dmg",
+ *         "sha256": "<64-hex>",
+ *         "label": "Download for macOS"
+ *       }
+ *     }
+ *
+ * The `url` is mutable (a Release asset can be re-uploaded); the `sha256` is
+ * the integrity anchor a client verifies the download against — the same
+ * "pin the immutable hash, not the mutable pointer" philosophy the source
+ * whitelist already enforces with full commit SHAs.
+ *
+ * An artifact is only surfaced when **both** fields are well-formed. A
+ * missing block, a non-`https:` URL, or an absent / placeholder `sha256`
+ * (e.g. the empty string a release workflow fills in on its first run) all
+ * resolve to `null` — "no downloadable artifact yet" — so a client never
+ * offers an unverifiable download.
+ */
+
+import { z } from "zod";
+
+/** A verified, downloadable client artifact declared by a plugin. */
+export interface PluginArtifact {
+  /** HTTPS URL the artifact is downloaded from. */
+  readonly url: string;
+  /** Lowercase 64-char hex SHA-256 the download is verified against. */
+  readonly sha256: string;
+  /**
+   * Optional human label for the download affordance — useful when a plugin
+   * ships more than one artifact (e.g. "Download for macOS", "Apple Silicon").
+   * Absent (or blank) when the plugin doesn't name it; clients fall back to a
+   * generic label.
+   */
+  readonly label?: string;
+}
+
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Schema for a complete artifact descriptor. The URL must be absolute and
+ * `https:` (an artifact fetched over plaintext defeats the integrity story);
+ * the digest must be canonical lowercase hex so client-side comparison is a
+ * plain string equality with no normalization step.
+ */
+const PluginArtifactSchema = z.object({
+  url: z
+    .string()
+    .url()
+    .refine((u) => u.startsWith("https://"), {
+      message: "artifact url must be an https:// URL",
+    }),
+  sha256: z
+    .string()
+    .regex(SHA256_HEX_RE, "artifact sha256 must be 64 lowercase hex chars"),
+  // Optional, non-critical metadata: a malformed label must never nullify an
+  // otherwise-valid `url` + `sha256`, so a wrong-typed value falls back to
+  // `undefined` rather than failing the whole descriptor.
+  label: z.string().optional().catch(undefined),
+});
+
+/**
+ * Read `vellum.artifact` from an already-parsed `package.json` value and
+ * return it only when it is a complete, well-formed descriptor. Any shape
+ * problem — missing block, wrong types, non-https URL, placeholder/empty
+ * `sha256` — yields `null` rather than throwing, so callers can union this
+ * across sources without per-source error handling.
+ */
+export function parsePluginArtifact(
+  packageJson: unknown,
+): PluginArtifact | null {
+  if (
+    typeof packageJson !== "object" ||
+    packageJson === null ||
+    Array.isArray(packageJson)
+  ) {
+    return null;
+  }
+  const vellum = (packageJson as Record<string, unknown>).vellum;
+  if (typeof vellum !== "object" || vellum === null || Array.isArray(vellum)) {
+    return null;
+  }
+  const artifact = (vellum as Record<string, unknown>).artifact;
+  const parsed = PluginArtifactSchema.safeParse(artifact);
+  if (!parsed.success) return null;
+  // A blank or whitespace-only label is treated as absent so it never
+  // invalidates an otherwise well-formed `url` + `sha256` descriptor.
+  const label = parsed.data.label?.trim();
+  return {
+    url: parsed.data.url,
+    sha256: parsed.data.sha256,
+    ...(label ? { label } : {}),
+  };
+}

package/src/cli/lib/plugin-details.ts

@@ -33,6 +33,7 @@ import {
   type FetchLike,
   sanitizePluginName,
 } from "./install-from-github.js";
+import { parsePluginArtifact, type PluginArtifact } from "./plugin-artifact.js";
 import {
   fetchMarketplaceEntries,
   type MarketplaceEntry,
@@ -56,6 +57,7 @@ interface PluginManifestFields {
   readonly description: string | null;
   readonly homepage: string | null;
   readonly license: string | null;
+  readonly artifact: PluginArtifact | null;
 }
 
 /** Options that control which plugin to resolve and at what ref. */
@@ -97,6 +99,13 @@ export interface PluginDetails {
   readonly readme: string | null;
   /** Git ref the catalog metadata / README were resolved at. */
   readonly ref: string;
+  /**
+   * Prebuilt client artifact (download URL + sha256) declared in the
+   * plugin's `package.json` `vellum.artifact`, resolved from the installed
+   * copy first then the repo; `null` when the plugin ships none or its
+   * descriptor is incomplete (e.g. a placeholder `sha256`).
+   */
+  readonly artifact: PluginArtifact | null;
 }
 
 /** No installed copy and no catalog/source entry claims the name. */
@@ -175,6 +184,7 @@ export async function getPluginDetails(
     source,
     readme,
     ref,
+    artifact: local.manifest.artifact ?? remote.manifest.artifact,
   };
 }
 
@@ -342,7 +352,13 @@ function githubFetch(
 }
 
 function emptyManifest(): PluginManifestFields {
-  return { version: null, description: null, homepage: null, license: null };
+  return {
+    version: null,
+    description: null,
+    homepage: null,
+    license: null,
+    artifact: null,
+  };
 }
 
 function safeParseManifest(raw: string): PluginManifestFields {
@@ -365,6 +381,7 @@ function parseManifest(raw: string): PluginManifestFields {
     description: typeof meta.description === "string" ? meta.description : null,
     homepage: typeof meta.homepage === "string" ? meta.homepage : null,
     license: normalizeLicense(meta.license),
+    artifact: parsePluginArtifact(parsed),
   };
 }
 

package/src/cli/lib/plugin-fingerprint.ts

@@ -0,0 +1,197 @@
+/**
+ * Content fingerprint of an installed plugin tree, used to detect local
+ * modifications after install.
+ *
+ * A plugin install is a flattened snapshot of a commit — the `.git` metadata is
+ * stripped during materialization (see {@link ./install-from-github}), so there
+ * is no working tree to ask `git status`. To tell whether a user has edited an
+ * installed copy, install records a per-file digest of the materialized tree in
+ * the provenance sidecar; later a recompute over the on-disk copy is compared
+ * against that baseline.
+ *
+ * The fingerprint is a one-way digest map — it answers "did this change?" and
+ * "which files?", but cannot reconstruct the original bytes. Producing an
+ * actual diff or a 3-way merge instead re-derives the baseline from the
+ * recorded immutable commit SHA (a separate concern from this module).
+ */
+
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Digest algorithm recorded alongside the file map, for forward compatibility. */
+export type FingerprintAlgorithm = "sha256";
+
+/**
+ * Per-file content digest of a plugin tree. Keys are POSIX-style
+ * (forward-slash) paths relative to the plugin root so the baseline is stable
+ * across platforms; values are lowercase hex digests of each file's bytes.
+ */
+export interface Fingerprint {
+  readonly algorithm: FingerprintAlgorithm;
+  readonly files: Readonly<Record<string, string>>;
+}
+
+/**
+ * Difference between a recorded fingerprint and the current on-disk tree.
+ * Paths are POSIX-relative, matching {@link Fingerprint.files}. A rename
+ * surfaces as one `removed` plus one `added` entry.
+ */
+export interface FingerprintComparison {
+  /** Present in both, but the content digest differs. */
+  readonly modified: readonly string[];
+  /** Present on disk, absent from the recorded baseline. */
+  readonly added: readonly string[];
+  /** Recorded in the baseline, absent on disk. */
+  readonly removed: readonly string[];
+  /** True when the on-disk tree exactly matches the recorded baseline. */
+  readonly clean: boolean;
+}
+
+function hashFile(absPath: string): string {
+  return createHash("sha256").update(readFileSync(absPath)).digest("hex");
+}
+
+/**
+ * Walk `root` and return a content digest for every regular file, keyed by its
+ * POSIX-relative path. Symlinks are skipped (the loader does not follow them,
+ * and install never materializes them); top-level entries named in `exclude`
+ * are skipped so the provenance sidecar never fingerprints itself.
+ */
+export function computeFingerprint(
+  root: string,
+  exclude: readonly string[] = [],
+): Fingerprint {
+  const excluded = new Set(exclude);
+  const files: Record<string, string> = {};
+
+  const walk = (relDir: string): void => {
+    const absDir = relDir ? join(root, relDir) : root;
+    for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+      if (relDir === "" && excluded.has(entry.name)) continue;
+      // Only regular files contribute to the digest; symlinks are never part of
+      // a materialized install and a directory is descended into, not hashed.
+      if (entry.isSymbolicLink()) continue;
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+      } else if (entry.isFile()) {
+        files[rel] = hashFile(join(root, rel));
+      }
+    }
+  };
+
+  walk("");
+  return { algorithm: "sha256", files };
+}
+
+/**
+ * Compare the current contents of `root` against a recorded fingerprint,
+ * applying the same `exclude` used to compute the baseline so the sidecar is
+ * not counted as an addition.
+ */
+export function compareFingerprint(
+  root: string,
+  baseline: Fingerprint,
+  exclude: readonly string[] = [],
+): FingerprintComparison {
+  const current = computeFingerprint(root, exclude).files;
+  const modified: string[] = [];
+  const added: string[] = [];
+  const removed: string[] = [];
+
+  for (const [path, digest] of Object.entries(current)) {
+    const recorded = baseline.files[path];
+    if (recorded === undefined) added.push(path);
+    else if (recorded !== digest) modified.push(path);
+  }
+  for (const path of Object.keys(baseline.files)) {
+    if (current[path] === undefined) removed.push(path);
+  }
+
+  modified.sort();
+  added.sort();
+  removed.sort();
+  return {
+    modified,
+    added,
+    removed,
+    clean: modified.length === 0 && added.length === 0 && removed.length === 0,
+  };
+}
+
+/**
+ * Parse a fingerprint from already-decoded JSON. Lenient by design — any shape
+ * problem yields `null` so an older or hand-edited sidecar simply reports "no
+ * recorded baseline" rather than throwing.
+ */
+export function parseFingerprint(value: unknown): Fingerprint | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const obj = value as Record<string, unknown>;
+  if (obj.algorithm !== "sha256") return null;
+  const rawFiles = obj.files;
+  if (
+    typeof rawFiles !== "object" ||
+    rawFiles === null ||
+    Array.isArray(rawFiles)
+  ) {
+    return null;
+  }
+  const files: Record<string, string> = {};
+  for (const [path, digest] of Object.entries(rawFiles)) {
+    if (typeof digest !== "string") return null;
+    files[path] = digest;
+  }
+  return { algorithm: "sha256", files };
+}
+
+/**
+ * Aggregate SHA-256 digest over a tree's contents, returned as `v2:<hex>`.
+ *
+ * This is the same scheme skills record in their `install-meta.json`
+ * `contentHash` (see `src/skills/install-meta.ts`): files are visited in
+ * POSIX-relative path order and each contributes a length-prefixed path
+ * segment followed by its length-prefixed bytes, so neither path/content
+ * boundaries nor reordering can collide. The `v2:` prefix marks the hashing
+ * scheme so it can evolve without ambiguity. Unlike {@link Fingerprint}, this
+ * is a single whole-tree digest — useful as a compact integrity signal
+ * alongside the per-file map. Symlinks are skipped and top-level entries named
+ * in `exclude` (e.g. the sidecar itself) are omitted, matching
+ * {@link computeFingerprint}.
+ */
+export function computeContentHash(
+  root: string,
+  exclude: readonly string[] = [],
+): string {
+  const excluded = new Set(exclude);
+  const entries: Array<{ rel: string; abs: string }> = [];
+
+  const walk = (relDir: string): void => {
+    const absDir = relDir ? join(root, relDir) : root;
+    for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+      if (relDir === "" && excluded.has(entry.name)) continue;
+      if (entry.isSymbolicLink()) continue;
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+      } else if (entry.isFile()) {
+        entries.push({ rel, abs: join(root, rel) });
+      }
+    }
+  };
+  walk("");
+  entries.sort((a, b) => a.rel.localeCompare(b.rel));
+
+  const hash = createHash("sha256");
+  for (const { rel, abs } of entries) {
+    const pathBuf = Buffer.from(rel, "utf-8");
+    const content = readFileSync(abs);
+    hash.update(`${pathBuf.length}:`);
+    hash.update(pathBuf);
+    hash.update(`${content.length}:`);
+    hash.update(content);
+  }
+  return `v2:${hash.digest("hex")}`;
+}